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PREFACE 



The Programmer's Library Reference Manual describes Fortran subprograms and functions available to 
users of the Cray operating systems COS L17,l and UNICOS 4.0 executing on CRAY Y-MP, 
CRAY X-MP EA, CRAY X-MP, and CRAY-1 computer systems. It supplements the information con- 
tained in the other manuals in the COS and UNICOS documentation sets. 

The System Library Reference Manual, publication SM-0114, describes internal system subprograms, 
Cray Assembly Language (CAL) subprograms* and Cray Pascal subprograms used by the Pascal com- 
piler. For COS 1.17.1 users, the Cray C Library Reference Manual, publication SR-0136 5.0, describes 
the C libraries available under COS (and UNICOS 5,0) on CRAY Y-MP, CRAY X-MP EA, CRAY X-MP, 
and CRAY-1 computer systems. For UNICOS 4.0 users, the CRAY Y-MP, CRAY X-MP, and CRAY-1 
C Library Reference Manual, publication SR-0136 C, describes the appropriate C library routines. 

The following Cray Research Inc. (CRI) manuals provide additional information about COS, UNICOS, 
and related subjects. Unless otherwise noted, all publications referenced in this manual are CRI publi- 
cations. 

COS Manuals: 

• Fortran (CFT) Reference Manual, publication SR-0009 

• COS Reference Manual, publication SR-0011 

• Macros and Opdefs Reference Manual for CRAY Y-MP, CRAY X-MP EA, CRAY X-MP, and 
CRAY-1 Computer Systems, publication SR-0012 

• Fortran (CFT) Internal Reference Manual, publication SM-0017 

• CFT77 Reference Manual, publication SM-0018 

• APML Assembler Reference Manual, publication SM-0036 

• COS Message Manual, publication SR-0039 

• Front-end Protocol Internal Reference Manual, publication SM-0042 

• COS Operational Procedures Reference Manual, publication SM-0043 

• Operational Aids Reference Manual, publication SM-0044 

• COS Table Descriptions Internal Reference Manual, publication SM-0045 

• IOS Software Internal Reference Manual, publication SM-0046 

• I/O Subsystem (IOS) Operator's Guide for COS, publication SG-0051 

• Pascal Reference Manual, publication SR-0060 

• Pascal Internal Reference Manual, publication SD-0061 

• Segment Loader (SEGLDR) and Id Reference Manual, publication SR-0066 

• Cray Simulator (CSIM) Internal Reference Manual, publication SM-0072 

• Cray Simulator (CSIM) Internal Reference Manual, publication SM-0073 

• CRAY Y-MP, CRAY X-MP EA, CRAY X-MP, and CRAY-1 CAL Assembler Version 2 Ready 
Reference, publication SQ-0083 

• Symbolic Machine Instructions Reference Manual, publication SR-0085 

• COS Dump Analysis Ready Reference, publication SQ-0096 

• System Library Reference Manual, publication SM-0114 

• Cray C Library Reference Manual, publication SR-0136 
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• CAL Assembler Version 2 Reference Manual, publication SR-2003 

• Cray C Reference Manual, publication SR-2024 

• The Guest Operating System (GOS), publication SMN-7013 

• Directory of Supercomputer Applications Software, publication ASD-86F 



UNICOS manuals: 

Introductory manuals: 

• UNICOS Overview for Users, publication SG-2052 

• UNICOS Primer, publication SG-2010 

• TCP/IP Network User Guide, publication SG-2009 

• UNICOS Text Editors Primer, publication SG-2050 

• UNICOS Tape Subsystem User's Guide, publication SG-2051 

• UNICOS Source Code Control System (SCCS) User's Guide, publication SG-2017 

• UNICOS Index for CRAY Y-MP, CRAY X-MP EA, CRAY X-MP, and CRAY-1 Computer 
Systems, publication SR-2049 

UNICOS reference manuals: 

• UNICOS User Commands Reference Manual, publication SR-2011 

• UNICOS User Commands Ready Reference, publication SQ-2056 

• UNICOS System Calls Reference Manual, publication SR-2012 

• UNICOS File Formats and Special Files Reference Manual, publication SR-2014 

• Fortran (CFT) Reference Manual, publication SR-0009 

• CFT77 Reference Manual, publication SR-0018 

• CAL Assembler Version 2 Reference Manual, publication SR-2003 

• Cray C Reference Manual, publication SR-2024 

• UNICOS vi Reference Card, publication SQ-2054 

• UNICOS ed Reference Card, publication SQ-2055 

• Network Library Reference Manual, publication SR-2057 

CONVENTIONS 

The following conventions are used throughout UNICOS documentation: 

command{\) Refers to an entry in the UNICOS User Commands Reference Manual, publication 
SR-201L 

command(lBSD) Refers to an entry in the UNICOS User Commands Reference Manual, publication 
SR-2011. 

command(lM) Refers to an entry in the UNICOS Administrator Commands Reference Manual, publi- 
cation SR-2022. 

system call(2) Refers to an entry in Volume 4: UNICOS System Calls Reference Manual, publication 
SR-2012. 
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routineQX) Refers to an entry in the appropriate CRI library reference manual. The letter or 
letters following the number 3 indicate that the routine is either COS-only or that the 
routine belongs to a specific UNICOS library, as follows: 



(3M) 


UNICOS math library 


(3SCI) 


UNICOS scientific library 


(3F) 


UNICOS Fortran library 


(3IO) 


UNICOS I/O library 


(3U) 


UNICOS utility library 


(3DB) 


UNICOS debugging library 



entry{AX) Refers to an entry in the UNICOS File Formats and Special Files Reference Manual, 

publication SR-2014. The letter following the number 4 indicates the section refer- 
ence. 

entryimio) Refers to an entry in the info section, which contains topical information that is not 
available in the UNICOS on-line manuals. The info man pages are not published in 
hard-copy form. 

All sections begin with an entry called intro, and the entries that follow the intro page are alphabet- 
ized Some entries may describe several routines. In such cases, the entry is usually alphabetized 
under its major name. 

In this manual, bold indicates all literal strings, including command names, directory names, file names, 
path names, library routine names, man page entry names, options, shell or system variable code names, 
system call names, C structures, and C reserved words. 

Italic indicates variable information usually supplied by you and words or concepts being defined. 

All entries are based on the following common format; however, most entries contain only some of 
these parts: 

NAME shows the name of the entry and briefly states its function. 

SYNOPSIS presents the syntax of the routine. The following conventions are used in this sec- 
tion: 

Brackets [ ] around an argument indicate that the argument is optional. 
DESCRIPTION discusses the entry in detail. 

IMPLEMENTATION provides details for using the command or routine with specific machines 
or operating systems; normally this will tell you under which operating system the routine is 
implemented 

NOTES points out items of particular importance. 

CAUTIONS describes actions that can destroy data or produce undesired results. 

WARNINGS describes actions that can harm people, damage equipment, or damage system 
software. 
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EXAMPLES shows examples of usage. 

FILES lists files that are either part of the entry or related to it. 

RETURN VALUE describes possible error returns. 

MESSAGES describes the informational, diagnostic, and error messages that may appear. 
BUGS indicates known bugs and deficiencies. 

SEE ALSO lists entries that contain related information and specifies the manual title for each 
entry. 

All entries in this manual that are applicable to your Cray computer system are available on-line 
through the man(l) command. To retrieve an entry, type the following, substituting the desired entry 
name for entry: 

man entry 

If there is more than one entry with the same name, all entries with that name will be printed. To 
retrieve the entry for a particular section, type the following, substituting the desired section name for 
section and the desired entry name for entry: 

man section entry 

For further information on the man command, see man(l). 
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READER COMMENTS 

If you have comments about the technical accuracy, content, or organization of this manual, please tell 
us. You can contact us in any of the following ways: 

• Call our Technical Publications department at (612) 681-5729* 

• Send us electronic mail from a UNICOS or UNIX system, using one of the following UUCP mail 
addresses: 

uunet ! cray ! publications 

sun ! tundra ! hall ! publications 

• Send us electronic mail from a UNICOS or UNIX system, using the following ARPAnet address: 

publications© cray .com 

• Send a facsimile of your comments to the attention of "Publications" at fax number (612) 681-5602. 

• Use the postage-paid Reader's Comment form at the back of this manual. 

■ Write to us at the following address: 

Cray Research, Inc. 
Technical Publications Department 
1345 Northland Drive 
Mendota Heights, MN 55120 

We value your comments and will respond to them promptly. 
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USSCTC Converts IBM 32-bit floating-point numbers 8-25 

USSCTI Converts Cray 64-bit single-precision, floating-point numbers 8-26 

VXDCTC Converts VAX 64-bit D format numbers «... 8-27 

VXDCTI Converts Cray 64-bit single-precision, floating-point numbers 8-28 

VXGCTC Converts VAX 64-bit G format numbers 8-29 

VXGCTI Converts Cray 64-bit single-precision, floating-point numbers 8-30 

VXICTC Converts VAX INTEGERS or INTEGERS 8-31 

VXICH Converts Cray 64-bit integers 8-32 

VXLCTC Converts VAX logical values to Cray 64-bit logical values 8-33 

VXSCTC Converts VAX 32-bit floating-point numbers 8-34 

VXSCTI Converts Cray 64-bit single-precision, floating-point 8-35 

VXZCTC Converts VAX 64-bit complex numbers to Cray complex numbers 8-36 
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9. PACKING ROUTINES 

INTRO 9-1 

PACK Compresses stored data 9-2 

P32, U32 Packs/unpacks 32-bit words into or from Cray 64-bit words 9-3 

P6460, U6064 Packs/unpacks 60-bit words into or from Cray 64-bit words 9-4 

UNPACK Expands stored data 9-5 

10. BYTE AND BIT MANIPULATION ROUTINES 

INTRO 10-1 

PUTBYT, IGTBYT Replaces a byte in a variable or an array 10-2 

FINDCH... Searches a variable or an array for an occurrence of a character string 10-3 

KOMSTR Compares specified bytes between variables or arrays 104 

STRMOV, MOVBIT Moves bytes or bits from one variable or array to another 10-5 

MVC Moves characters from one memory area to another. 10-6 

TRIMLEN Returns the number of characters in a string 10-7 



11. HEAP MANAGEMENT AND TABLE MANAGEMENT 

INTRO 11-1 

HPALLOC Allocates a block of memory from the heap 11-4 

HPCHECK* Checks the integrity of the heap 11-5 

HPCLMOVE Extends a block or copies block contents into a larger block 11-6 

HPDEALLC Returns a block of memory to the list of available space 1 1-7 

HPDUMP Dumps the address and size of each heap block „. 11-8 

HPNEWLEN... Changes the size of an allocated heap block 11-9 

HPSHRINK Returns an unused portion of heap to the operating system 11-10 

IHPLEN Returns the length of a heap block 11-11 

IHPSTAT Returns statistics about the heap 11-12 

TMADW Adds a word to a table 11-13 

TMAMU Reports table management operation statistics 11-14 

TMATS Allocates table space 11-15 

TMMEM. Requests additional memory 11-16 

TMMSC Searches the table with a mask to locate a specific field 11-17 

TMMVE Moves memory (words) 11-18 

TMPTS Presets table space 11-19 

TMSRC Searches the table wilh an optional mask to locate a specific field 11-20 

TMVSC Searches a vector table for the search argument 11-21 

12. I/O ROUTINES 

INTRO 12-1 

ACPTBAD Makes bad data available 12-9 

AQCLOSE Closes an asynchronous queued I/O dataset or file 12-11 

AQOPEN Opens a dataset or file for asynchronous queued I/O 12-12 

AQOPENDV Opens a dataset or file for asynchronous queued I/O (size, location) 12-13 
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AQREAD, AQREADC, 

AQREADI, AQREADCI Queues a simple or compound asynchronous I/O read request 12-15 

AQRECALL, AQRIR Delays program execution during a queued I/O sequence 12-17 

AQSTAT Checks the status of asynchronous queued I/O requests 12-19 

AQSTOP Stops the processing of asynchronous queued I/O requests 12-20 

AQWAIT Waits on a completion of asynchronous queued I/O requests 12-21 

AQWRITE, AQWRITEC, 

AQWRITEI, AQWRTECI Queues a simple or compound asynchronous I/O write request.. 12-22 

ASYNCMS, ASYNCDR Sets I/O mode for random access routines to asynchronous 12-24 

CHECKMS, CHECKDR Checks status of asynchronous random access I/O operation 12-25 

CHECKTP Checks tape I/O status 12-26 

CLOSEV Begins user EOV and BOV processing 12-27 

CLOSMS, CLOSDR Writes master index and closes random access dataset 12-28 

CONTPIO Continues normal I/O operations 12-30 

ENDSP Requests notification at the end of a tape volume 12-31 

FTNDMS Reads record into data buffers 12-32 

FSUP > ISUP, FSUPC, IS UPC Output a value in an argument as blank or return to ordinary I/O 12-33 

GETPOS, SETPOS Returns the current position of interchange tape 12-34 

GETTP Receives position information about an opened tape dataset or file 12-36 

GETWA, SEEK Synchronously and asynchronously reads data 12-38 

GETWAU Asynchronously reads a number of words from the disk, directly to user.. 1240 

OPENMS, OPENDR Opens a local dataset as a random access dataset 12-42 

PROCBOV Allows special processing at beginning-of- volume (obsolete) 1244 

PROCEOV Begins special processing at end-of- volume (EOV) (obsolete) 12-45 

PUTWA, APUTWA Writes to a word-addressable, random-access dataset 1246 

PUTWAU Writes to a word-addressable, random-access dataset, unbuffered 1247 

READ, READP Reads words, full or partial record modes 1249 

READC, READCP Reads characters, full or partial record mode 12-50 

READIBM Reads two IBM 32-bit floating-point words 12-51 

READMS, READDR Reads a record from a random-access dataset 12-52 

RNLFLAG, RNLDELM, RNLSEP, 

RNLREP, RNLCOMM Adds or deletes characters recognized by NAMELIST 12-54 

RNLECHO Specifies output unit for NAMELIST error messages 12-55 

RNLSKIP Takes appropriate action with an undesired NAMELIST group 12-56 

RNLTYPE Determines action if a type mismatch occurs on an input record 12-57 

SETSP Requests notification at the end of a tape volume * 12-58 

SETTP Positions a tape dataset or file 12-59 

SKIPBAD Skips bad data 12-61 

STARTSP Begins user EOV and BOV processing 12-62 

STTNDX, STINDR Allows an index to be used as the current index 12-63 

SVOLPRC Initializes/terminates special BOV/EOV processing (obsolete) 12-65 

SWITCHV Switches tape volume 12-66 

SYNCH Synchronizes the program and an opened tape dataset 12-67 

SYNCMS, SYNCDR Sets I/O mode for random access routines to synchronous 12-68 

WATTMS, WAITDR Waits for completion of an asynchronous I/O operation 12-69 

WCHECK Checks word-addressable file status 12-70 

WCLOSE Closes a word-addressable, random-access dataset 12-71 

WCLOSEU Closes a word-addressable, unbuffered random-access dataset 12-72 

WNLFLAG, WNLDELM, 

WNLSEP, WNLREP Provides user control of output 12-73 

WNLLINE Allows each NAMELIST variable to begin on a new line 12-74 

WNLLONG Indicates output line length 12-75 

WOPEN Opens a word-addressable, random-access dataset 12-76 

WOPENU Opens a word-addressable, random-access dataset, unbuffered 12-78 
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WRITE, WRITE? . Writes words, full or partial record mode 12-80 

WRITEC, WRITECP Writes characters, full or partial record mode 12-81 

WRITIBM Writes two IBM 32-bit floating-point words 12-82 

WRITMS, WRITDR Writes to a random-access dataset on disk 12-83 



13, DATASET UTILITY ROUTINES 

INTRO 13-1 

B ACKHLE Positions a dataset after the previous EOF 13-3 

COPYR, COPYF, COPYD Copies records, files, or a dataset 13-4 

COPYU Copies either specified sectors or all data to EOD 13-5 

EODW Terminates a dataset by writing EOD, EOF, and EOR1 13-6 

EOF, EOF Returns real or integer value EOF status 13-7 

IOSTAT Returns EOF and EOD status 13-8 

NUMBLKS Returns the current size of a dataset in 512-word blocks 13-9 

SKIPD Positions a blocked dataset at EOD 13-10 

SKIPR, SKIPF Skip records or files 13-11 

SKIPU... Skips a specified number of sectors in a dataset 13-13 



14. MULTITASKING ROUTINES 

INTRO 14-1 

BARASGN... Identifies an integer variable to use as a barrier 14-5 

BARREL Releases the identifier assigned to a barrier 14-6 

BARSYNC Registers the arrival of a task at a barrier 14-7 

BUFDUMP... Unformatted dump of multitasking history trace buffer 14-8 

BUFPRINT Formatted dump of multitasking history trace buffer 14-9 

BUFTUNE.... Tune parameters controlling multitasking history trace buffer 14-10 

BUFUSER Adds entries to the multitasking history trace buffer „„. 14-13 

EVASGN Identifies an integer variable to be used as an event 14-14 

EVCLEAR Clears an event and returns control to the calling task 14-15 

EVPOST Posts an event and returns control to the calling task.. 14-16 

EVREL Releases the identifier assigned to the task + 14-17 

EVTEST Tests an event to determine its posted state 14-18 

EVWAIT Delays the calling task until the specified event is posted 14-19 

JCCYCL Returns machine cycle time,™ * 14-20 

LOCKASGN Identifies an integer variable intended for use as a lock 14-21 

LOCKOFF Clears a lock and returns control to the calling task 14-22 

LOCKON Sets a lock and returns control to the calling task . 14-23 

LOCKREL Releases the identifier assigned to a lock „ 14-24 

LOCKTEST Tests a lock to determine its state (locked or unlocked) 14-25 

MAXLCPUS Returns the maximum number of logical CPUs 14-26 

TSECND Returns elapsed CPU time for a calling task 14-27 

TSKSTART Initiates a task 14-28 

TSKTEST Returns a value indicating whether the indicated task exists 14-29 

TSKTUNE Modifies tuning parameters within the library scheduler 14-30 

TSK VALUE Retrieves user identifier specified in task control array 14-31 

TSKWAIT Waits for the indicated task to complete execution 14-32 
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15. TIMING ROUTINES 

INTRO 15-1 

CLOCK Returns the current system-clock time 15-3 

DATE, JDATE. Returns the current date and the current Julian date 154 

DTTS Converts ASCII date and time to time-stamp 15-5 

RTC, IRTC... Returns real-time clock values 15-6 

SECOND Returns elapsed CPU time 15-7 

TIMEF Returns elapsed wall-clock time since the call to TIMEF 15-8 

TREMAIN Returns the CPU time (in floating-point seconds) 15-9 

TSDT Converts time-stamps to ASCII date and time strings... 15-10 

TSMT, MTTS Converts time-stamp to a corresponding real-time value, and vice versa... 15-11 

UNITTS Returns time-stamp units in specified standard time units 15-12 



16. PROGRAMMING AID ROUTINES 

INTRO 16-1 

CRAYDUMP Prints a memory dump to a specified dataset 16-3 

DUMP, PDUMP Dumps memory to $OUT 164 

DUMPJOB Creates an unblocked dataset containing the user job area image 16-5 

FXP Formats and writes the contents of the Exchange Package 16-6 

GETNAMEQ Returns name of the caller 16-7 

IGETSEC Returns the cycles charged to a job 16-8 

PERF Provides an interface to the hardware performance monitor 16-9 

SETPLIMQ Initiates detailed tracing of every call and return 16-12 

SNAP Copies current register contents to $OUT 16-13 

SYMDEBUG Produces a symbolic dump 16-14 

SYMDUMP Produces a snapshot dump of a running program 16-16 

TRBK Lists all subroutines active in the current calling sequence 16-20 

TRBKLVL Returns information on current level of calling sequence 16-21 

XPFMT Produces a printable image of an Exchange Package 16-22 



17. SYSTEM INTERFACE ROUTINES 

INTRO 17-1 

ABORT Requests abort with traceback 17-5 

ACTTABLE Returns the Job Accounting Table (JAT) 17-6 

CCS Cracks a control statement 17-7 

CEXPR Cracks an expression 17-8 

CLEARBT, SETBT Temporarily disables/enables bidirectional memory transfers 17-9 

CLEARBTS, SETBTS Permanently disables/enables bidirectional memory transfers 17-10 

CLEARFI, SETFI Temporarily prohibitsftermits floating-point interrupts... 17-11 

CLEARHS, SETFIS Temporarily prohibits/^rmits floating-point interrupts 17-12 

CRACK Cracks a directive 17-13 

DELAY Do nothing for a fixed period of time 17-14 

DRIVER Programs a Cray channel on an I/O Subsystem (IOS) 17-15 

ECHO Turns on and off the classes of messages to the user logfile.... 17-16 

END, ENDRPV Terminates a job step 17-17 

ERECALL Allows a job to suspend itself until selected events occur 17-18 

ERREXIT.„. Requests abort 17-20 

EXIT Exits from a Fortran program 17-21 

GETARG Returns Fortran command-line argument 17-22 
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GETLPP Returns lines per page 17-23 

GETPARAM Gets parameters 17-24 

IARGC Returns number of command line arguments 17-26 

ICEIL Returns integer ceiling of a rational number 17-27 

UCOM... . Allows a job to communicate with another job 17-28 

ISHELL Executes a UMCOS shell command 17-30 

JNAME Returns the job name 17-31 

JSYMSET, JSYMGET Changes a value for a JCL symbol 17-32 

LGO Loads an absolute program from a dataset 17-33 

LOC Returns memory address of variable or array , 17-34 

MEMORY.. Manipulates a job's memory allocation 17-35 

NACSED Returns the edition of a previously-accessed permanent dataset 17-37 

OVERLAY Loads an overlay 17-38 

PPL Processes keywords of a directive 17-39 

REMARK2, REMARK Enters a message in the user and system log files 1740 

REMARKF Enters a formatted message in the user and system logfiles 1741 

RERUN, NORERUN Declares a job rerunnablo/not rerunnable 1742 

SENSEBT Determines whether bidirectional memory transfer is enabled 1743 

SENSEFI Determines if floating-point interrupts are permitted 1744 

SETRPV # Conditionally transfers control to a specified routine 1745 

SMACH, CMACH........ Returns machine epsilon, small/large normalized numbers 1746 

SSWITCH Tests the sense switch 1747 

SYSTEM Makes requests of the operating system 1748 



18. INTERFACE TO C LIBRARY ROUTINES 

INTRO 18-1 

getenv Returns value for environment name 184 

GETOPT Gets an option letter from an argument vector 18-5 

uname Gets name of current operating system 18-8 



19, MISCELLANEOUS UNICOS ROUTINES 

INTRO 19-1 

curses Updates CRT screens 19-2 

xio Text interface to the X Window System 19-8 

Xlib , C Language X Window System Interface Library 19-10 
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1. INTRODUCTION 



This manual describes Fortran programming subprograms provided in the standard COS libraries 
$ARLIB, SFTLIB, SIOLEB, SSCILTO, SSYSLffi, and SUTLIB, and those subprograms supported by UNICOS 
on the CRAY Y-MP, CRAY X-MP, and CRAY-1 computer systems. The Cray Assembly Language (CAL) 
subprograms and subprograms called by code generated by the Cray Fortran compiler or the Cray Pas- 
cal compiler are described in Volume 6: UNICOS Internal Library Reference Manual, publication 
SM-2083. Routines generated in the form of in-line code are generally not included in this manual, but 
they are described in the Fortran (CFT) Reference Manual, publication SR-0009, and the CFT77 Refer- 
ence Manual, publication SR-0018. 

The routines are divided into functional sections. A brief description of each section follows: 



Section Description 

1 Introduction 

2 Common Mathematical Subprograms - General arithmetic, exponentiation, loga- 
rithmic, trigonometric, character, type conversion, and Boolean functions 

3 COS Dataset Management Subprograms - COS Job Control Language (JCL) routines 

4 Linear Algebra Subprograms - Basic linear algebra, linear recurrence, matrix inverse 
and multiplication, filter, gather/scatter, and LINPACK/EISPACK routines 

5 Fast Fourier Transform Routines - Computing Fourier analysis and Fourier synthesis 
routines 

6 Search Routines - Maximum and minimum search and vector search routines 

7 Sorting Routines - ORDERS optimized sort routine 

8 Conversion Subprograms - Foreign dataset conversion (IBM, CDC, and VAX), 
numeric conversion, and miscellaneous conversion routines 

9 Packing Routines - Packing and unpacking data routines 

10 Byte and Bit Manipulation Routines - Routines for comparing, moving, and search- 
ing at the element level 

1 1 Heap Management and Table Management Routines - Routines for manipulating and 
managing memory within heaps and tables 

12 I/O Routines - Dataset positioning, auxiliary NAMELIST, logical record, random 
access dataset, and output suppression routines 

13 Dataset Utility Routines - Routines for positioning, copying, and skipping datasets 

14 Multitasking Routines - Task, lock, event, and history trace buffer routines 

15 Timing routines - Time-stamp and time/date routines 

16 Programming Aids Routines - Flowtrace, traceback, dump, Exchange Package pro- 
cessing, and hardware performance routines 

17 System Interface Routines - JCL symbol, control statement processing, job control, 
floating-point interrupt, bidirectional memory transfer, and special purpose interface 
routines 
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Section Description 

18 Interfaces to C Library Routines - C library interface routines available under 
UNICOS and documented in the CRAY Y-MP, CRAY X-MP, and CRAY-1 C Library 
Reference Manual, publication SR-0136 C, and the UNICOS System Calls Reference 
Manual, publication SR-2012. 

19 Miscellaneous UNICOS Routines - X Window System routines and libraries. 

SUBPROGRAM CLASSIFICATION 

Unless otherwise noted, all routines in this manual are described as Fortran subroutines or Junctions. In 
some cases (e.g., SECOND), the routine may be called as either a subroutine or a function. The Fortran 
compilers will, however, enforce consistency in any one compilation unit. 

Programs written in C can call library functions intended for use by Fortran programs. The C program- 
mer is responsible for passing arguments by address and not by value, as is the normal case in C. 

C programs can also be written to accommodate Fortran users. Such programs must be written to 
accept arguments passed by address rather than passed by value, as in the normal case in C. 

Pascal programs can call library functions intended for use by Fortran programs. Similarly, Fortran 
codes can invoke subroutines and functions written in Pascal. Unlike C, the Pascal compiler passes all 
arguments by address, and supports several predefined conversion functions to facilitate communication 
with Fortran routines. See the Pascal Reference Manual, publication SR-0060, for information regarding 
parameter passing, data formats, and restrictions. 

LINKAGE METHODS 

The externally-callable library routines are accessed by one of two methods: call-by-address or call-by- 
value. Subroutines are always called by address. Fortran accesses intrinsic library functions or user 
functions named in a VFUNCTION directive in either call-by-address or call-by-value mode, depending 
on context 

In call-by-address mode, addresses of arguments are stored sequentially in memory. Functions return 
their results in registers. Subroutines return results through their argument lists (for information on the 
calling sequence, see the Macros and Opdefs Reference Manual for CRAY Y-MP, CRAY X-MP EA, 
CRAY X-MP, and CRAY-1 Computer Systems, CRI publication SR-0012). 

In call-by-value mode, arguments are loaded into either scalar (S) or vector (V) registers, and the func- 
tion returns its result in SI or VI. S2 or V2 is used for complex or double-precision functions. Vector 
functions must also have the vector length present in the vector length (VL) register. 

Linkage macros generate code to handle subprogram linkage between compiled routines and CAL- 
assembled routines. These linkage macros and their uses follow. 



Macro Description 

CALL Provides linkage to call-by-address routines 

CALLV Provides linkage to call-by-value routines 

ENTER Reserves space for parameter addresses, saves 

B and T registers, and sets up traceback linkage 

EXIT Initiates a return from a routine to its caller and 



restores any B or T registers not considered scratch 
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Linkage macros should be used whenever possible to maintain compatibility with future CRI software. 
See the Macros and Opdefs Reference Manual for CRAY Y-MP, CRAY X-MP EA, CRAY X-MP, and 
CRAY-l Computer Systems, CRI publication SR-0012), for detailed descriptions of linkage macros and 
linkage conventions. 

All Cray library subroutines can use any of the A, S, V, VL, VM> B70 through B77, and T70 through 
T77 registers as scratch registers; therefore, the calling routine should not depend on any of these regis- 
ters being preserved. These routines, however, preserve the contents of registers B01 through B65 and 
TOO through T67 (all registers are numbered in octal). 



NOTE 

CRI reserves the right to make future use of any of the 
A, S, V, VL, VM, B66-B77, and T70-T77 registers in any 
library subroutine. You cannot depend on the contents 
of these registers being preserved in any library 
routine. 

CRI also reserves subroutine names beginning with the characters 
100 for internal use only. 
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2. COMMON MATHEMATICAL SUBPROGRAMS 



The math library contains routines that are accessible to Cray Fortran (CFT and CFT77) t Cray C, and 
Cray Assembly Language (CAL), 

This introductory section is divided into the following categories of mathematical routines: 

• General arithmetic functions 

• Exponential and logarithmic functions 

• Trigonometric functions 

• Character functions 

• Type conversion functions 

• Boolean functions 

In this section, each category of routines is given a general introduction. The routines are then listed in 
tabular form, displaying purpose, name, and manual entry (the name of the manual page containing 
documentation for the routine). 

Following this introductory section, the manual pages for the routines appear in alphabetical order, usu- 
ally by generic function name. 

Generic function names are function calls that cause the Fortran compiler to automatically compile the 
appropriate data type version of a routine, based on the type of the input data. For example, a call to 
the generic function LOG with type complex input data will compile as CLOG. 

In general, real functions have no prefix, integer functions are prefixed with I, double-precision func- 
tions are prefixed with D, and complex functions are prefixed with C (for example ABS, IABS, DABS, 
and CABS), Arguments are given in their type: real, integer, complex, logical, Boolean, and double 
(double precision); results are given as r, i, z, I, b, and d for real, integer, complex, logical, Boolean, 
and double precision, respectively. Functions with a type different from their arguments are noted. 
Real functions are usually the same as the generic function name. 

The math routines available through the normal C calling sequence, identified by lowercase names, 
have the appropriate declarations listed in the Synopsis section of their manual pages. To assure a clear 
distinction between Fortran and C information, headings of "Fortran:" and "C:" are used in the Synopsis 
and Notes sections of relevant manual pages - even when only one language is mentioned on a page. 

The documentation for some of the most often used math library routines also contains information on 
Cray Assembly Language (CAL) register usage. 

For more information on calling library routines from various programming languages, see the Notes on 
Calling Functions from Fortian, C, or Cray Assembly Language (CAL), in the Preface of this manual. 
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General Arithmetic Functions 

The general arithmetic functions are based upon ANSI standards for Fortran and C, with the exception 
of the pseudo-random number routines (RANF, RANGET, and RANSET), which are CR1 extensions. 

In the routine descriptions, complex arguments are represented such that 
x = x t + i * JCi 

where x T is the real portion and i * x x is the imaginary portion of the complex number. Arguments 
and results are of the same type unless otherwise indicated. 

Base values raised to a power and 64-bit integer division are implicitly called from Fortran. 

The following table contains the purpose, name, and manual entry of each general arithmetic function. 
The "manual entry" is the name of the manual page containing documentation for the routine(s) listed. 



General Arithmetic Functions 


Purpose 


Name 


Manual Entry 


Compute absolute value for real, 
integer, double-precision, and 
complex numbers 


ABS 
IABS 
DABS 
CABS 


ABS 


Compute the imaginary portion of a 
complex number 


AIMAG 


AIMAG 


Compute real and double-precision 
truncation 


AINT 
DINT 


AINT 


Compute the conjugate of a complex 
number 


CONJG 


CONJG 


Find the positive difference of 
real, integer, or double-precision 
numbers 


DIM 

IDIM 

DDIM 


DIM 


Compute the double-precision product 
of two real numbers 


DPROD 


DPROD 


Remainder of x t /x 2 
for integer, real, and double- 
precision numbers 


MOD 

AMOD 

DMOD 


MOD 


Find the nearest whole number for 
real and double-precision numbers 


ANINT 
DNINT 


ANINT 


Find the nearest integer for real 
and double-precision numbers 


NINT 
IDNINT 


NINT 


Obtain and establish a pseudo- 
random number seed 


RANGET 
RANSET 


RAN 


Obtain the first or next number in 
a series of pseudo-random numbers 


RANF 


Transfer the sign of a real, integer, 
or double-precision number 


SIGN 

ISIGN 

DSIGN 


SIGN 
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Exponential and Logarithmic Functions 

The CRI exponential and logarithmic functions are similar to the ANSI standard functions. Each func- 
tion has variations for real, double-precision, and complex values except the common logarithm func- 
tion, which only addresses real and double-precision values. Complex arguments are represented such 
that 

jc = x T + i * Xi 

where x t is the real portion and i * Xi is the imaginary portion of the complex number. 

The following lable contains the purpose, name, and manual entry of each exponential and logarithmic 
function. 

The "manual entry" is the name of the manual page containing documentation for the routine(s) listed. 



Exponential and Logarithmic Functions 


Purpose 


Name 


Manual Entry 


Compute the natural logarithm for 
real, double-precision, and 
complex numbers 


ALOG 
DLOG 
CLOG 


LOG 


Compute the common logarithm for real 
and double-precision numbers 


ALOG10 
DLOG10 


LOG10 


Compute exponents for real, double- 
precision, and complex numbers 


EXP 

DEXP 

CEXP 


EXP 


Compute the square root for real, 
double-precision, and complex numbers 


SQRT 

DSQRT 

CSQRT 


SQRT 
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Trigonometric Functions 

The trigonometric functions are based on the ANSI standard for Fortran and C, except for the cotangent 
function, which is a CRI extension. 

The following table contains the purpose, name, and manual entry of each trigonometric function. 
The "manual entry*' is the name of the manual page containing documentation for the n>utine(s) listed. 



Trigonometric Functions 


Purpose 


Name 


Manual Entry 


Compute the arcsine for real and 
double-precision numbers 


ASIN 
DASIN 


ASIN 


Compute the arccosine for real and 
double-precision numbers 


ACOS 
DACOS 


ACOS 


Compute the arctangent with one 
real or double-precision argument 


ATAN 
DATAN 


ATAN 


Compute the arctangent with two 
real or double-precision arguments 


ATAN2 
DATAN2 


ATAN2 


Compute the cosine for real, double- 
precision, and complex numbers 


COS 

DCOS 

CCOS 


COS 


Compute the hyperbolic cosine for real 
and double-precision numbers 


COSH 
DCOSH 


COSH 


Compute the sine for real, double- 
precision, and complex numbers 


SIN 

DSIN 

CSIN 


SIN 


Compute the hyperbolic sine for real 
and double-precision numbers 


SINH 
DSINH 


SINH 


Compute the tangent for real and 
double-precision numbers 


TAN 
DTAN 


TAN 


Compute the cotangent for real and 
double-precision numbers 


COT 
DCOT 


COT 


Compute the hyperbolic tangent for real 
and double-precision numbers 


TANH 
DTANH 


TANH 
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Character Functions 

Character functions compare strings, determine the lengths of strings, and return the index of a sub- 
string within a string. The character functions are ANSI standard functions. 

The comparison functions return a logical value of true or false when two character arguments are com- 
pared according to the ANSI collating sequence. These four functions are found under the entry 
LGE(3F), 

The routines for determining the length of a string and the index of a substring are found under the 
entries LEN(3F) and INDEX(3F), respectively. 

Type Conversion Functions 

Type conversion functions change the type of an argument The following table contains the purpose, 
name, and manual entry of each type conversion routine. 

The "manual entry" is the name of the manual page containing documentation for the routine(s) listed. 

In the routine description, complex arguments are represented such that x = x T + i * x i9 Arguments 
and results are of the same type, unless indicated otherwise. 



Type Conversion Routines 


Purpose 


Name 


Manual Entry 


Convert type character to integer 


ICHAR 


CHAR 


Convert type integer to character 


CHAR 


Convert to type complex 


CMPLX 


CMPLX 


Convert to type double precision 


DBLE 


DBLE 


Convert integer to double precision 


DFLOAT 


Convert to type integer 


INT 

IFIX 

IDINT 


INT 


Convert a 64-bit integer to a 
24-bit integer 


INT24 


INT24 


Convert a 24-bit integer to a 
64-bit integer 


LINT 


Convert to type real 


REAL 

FLOAT 

SNGL 


REAL 
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Boolean Functions 

The Boolean functions perform logical operations and bit manipulations. 

The scalar subprograms in the following table are external versions of Fortran in-line functions. These 
functions can be passed as arguments to user-defined functions. They are all called by address; results 
are returned in register SI, All Boolean functions are CRI extensions. 

The "manual entry" is the name of the manual page containing documentation for the routine(s) listed. 



Boolean Arithmetic Routines 



Purpose 


Name 


Manual Entry 


Compute the logical product 


AND 


AND 


Compute the logical complement 


COMPL 


COMPL 


Compute the logical equivalence 


EQV 


EQV 


Count the number of leading 0 bits 


LEADZ 


LEADZ 


Return a bit mask 


MASK 


MASK 


Compute the logical difference (same as XOR) 


NEQV 


NEQV 


Compute the logical sum 


OR 


OR 


Count the number of bits set to 1 


POPCNT 


POPCNT 


Compute the bit population parity 


POPPAR 


POPPAR 


Perform a left circular shift 


SHIFT 


SHIFT 


Perform a left shift with zero fill 


SHIFTL 


SHIFTL 


Perform a right shift with zero fill 


SHIFTR 


SHIFTR 


Compute the logical difference (same as NEQV) 


XOR 


NEQV 



SEE ALSO 

Fortran (CFT) Reference Manual, publication SR-0009 
CFT77 Reference Manual, publication SR-0018 
Cray C Reference Manual, publication SR-2024 
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NAME 

ABS, IABS, DABS, CABS - Computes absolute value 

SYNOPSIS 

Fortran: 

r = ABS(r*a/) 
/ = IAB$(integer) 
d = DABSOfcwWe) 
r = CAhS(complex) 



CAL register usage: 
Scalar IABS: 

IABS% (call by register) 
on entry (SI) =* argument 
on exit (SI) « result 



Scalar DABS; 

DABS% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Scalar CABS: Vector CABS: 

CABS% (call by register) %CABS% (call by register) 

on entry (SI) and (S2) = argument on entry (VI) = argument vector 1 (real portion) 
on exit (SI) = result (V2) = argument vector 2 (imaginary portion) 

on exit (VI) = result vector 



DESCRIPTION 

These functions evaluate y = | x | , except for CABS, which evaluates 
y = I C*r 2 + 



ABS returns the real absolute value of its real argument. 

IABS returns the integer absolute value of its integer argument. 

DABS returns the double-precision absolute value of its double-precision argument. 

CABS returns the real absolute value of its complex argument 

ABS is the generic function name. 

ABS, IABS, DABS, and CABS are intrinsic for CFT and CFT77. 
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ARGUMENT RANGE 

ABS, IABS, DABS: 

\x\<oo (oo = 10 2 **) 

CABS: 

K U*i l<°° 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems, 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 

Level of vectorization: Full 

Code generation: ABS, IABS, DABS: In-line 
CABS: External 

RETURN VALUE 

When the correct value would overflow, CABS aborts with a floating-point error. 
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NAME 

ACOS, DACOS, acos - Computes arccosine 
SYNOPSIS 

Fortran: 

r = ACOS</raO 
d = DACOS(double) 



C: 

^include <math.h> 
double acos(x) 
double x; 



CAL register usage: 
Scalar ACOS: 

ACOS% (call by register) 
on entry (SI) - argument 
on exit (SI) = result 



Vector ACOS: 

%ACOS% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 



Scalar DACOS: 

DACOS% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector DACOS: 

% DACOS % (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate y = arccos(x). 

ACOS and acos (callable only from C programs) return the real arccosine of their real argument. 
DACOS returns the double-precision arccosine of its double-precision argument 

ACOS is the generic function name. 

ACOS and DACOS are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 
|* j< LO 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard; ANSI standard 
Level of vectorization: Full 
Code generation: External 
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ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 

AIMAG - Computes imaginary portion of a complex number 

SYNOPSIS 

Fortran: 

t - AIMAG (complex) 

DESCRIPTION 

This function evaluates 

y =*i. 

AIMAG returns the imaginary portion of its complex argument. 
AIMAG is intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

I X t | , | X { I < oo (00 = 10 2466 ) 

EXAMPLE 

PROGRAM AIMTEST 
REAL RESULT 
RESULT=AIMAG( (1 .0,2.0) ) 
PRINT *, RESULT 
STOP 
END 



The preceding program gives the imaginary portion of the complex number (1 .0,2.0). After running the pro- 
gram, RESULT=2.0. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: In-line 
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NAME 

AINT, DINT - Computes real and double-precision truncation 

SYNOPSIS 

Fortran: 

r = AINT(rea/) 
d = DWT(double) 

DESCRIPTION 

These functions evaluate y * L*J without rounding. 

AINT truncates the fractional part of its real argument. The fractional part is lost (not rounded). 

DINT truncates the fractional part of its double-precision argument. The fractional part is lost (not 

rounded). 

AINT is the generic function name. 

AINT and DINT are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 
AINT: 

\x\k2 46 

DINT: 

|*|<2* 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 

Level of vectorization: FuU 

Code generation: AINT: In-line 
DINT: External 
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NAME 

ALOG, DLOG, CLOG, log - Computes natural logarithm 
SYNOPSIS 



Fortran: 

r = ALOG(rra/) 
d = VhOG(double) 
z = CLOG(complex) 



C: 

finclude <raath.h> 
double log(x) 
double x; 



CAL register usage: 
Scalar ALOG: 

ALOG% (call by register) 
on entry (SI) = argument 
on exit (SI) - result 



Vector ALOG: 

%ALOG% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 



Scalar DLOG: 

DLOG% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) « result 



Vector DLOG: 

%DLOG% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



Scalar CLOG: 

CLOG% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector CLOG: 

%CLOG% (call by register) 

on entry (VI) and (V2) - argument vector 

on exit (VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate y ~ ln(x). 

ALOG and log (callable only from C programs) return the real natural logarithm of their real argument 
DLOG returns the double-precision natural logarithm of its double-precision argument. 
CLOG returns the complex natural logarithm of its complex argument. 

LOG is the generic function name. 

ALOG, DLOG, and CLOG are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

0 < x < ~ (00= 10 246 *) 

IMPLEMENTATION 

These routines are available to users of both the COS and UMCOS operating systems. 
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NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 

C: 

ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 



ALOG10, DLOG10, loglO - Computes common logarithm 
SYNOPSIS 



Fortran: 

r = ALOG10(reaO 
d = DLOG10(<fcu«€) 



C: 

♦include <math.h> 
double loglO(x) 
double x; 



CAL register usage: 

Scalar ALOG10: 

ALOG10% (call by register) 
on entry (SI) = argument 
on exit (SI) = result 



Vector ALOG10: 

%ALOG10% (call by register) 
on entry (VI) = argument vector 
on exit (VI) = result vector 



Scalar DLOG10: 

DLOG10% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector DLOG10: 

%DLOG10% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate y = logOc). 

ALOG10 and loglO (callable only from C programs) return the real common logarithm of their real 
argument. 

DLOG10 returns the double-precision common logarithm of its double-precision argument. 

LOGIO is the generic function name. 

ALOG10 and DLOG10 are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

0 < X < oo (oo ^ 10 2466 ) 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 
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ANSI C standard or Cray extension to standard: ANSI standard 
Level of vcctorization: None 
Code generation: External 
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NAME 

AND - Computes logical product 

SYNOPSIS 

Fortran: 

/ = Afil>(IogicaUogical) 
b = AND(arg,arg) 

DESCRIPTION 

arg - CFT77: type Boolean, integer, real, or pointer 
CFT: type Boolean, integer, or real 

When given two arguments of type logical, AND computes a logical product and returns a logical result. 
When given two arguments of type Boolean, integer, real, or pointer, AND computes a bit-wise logical 
product and returns a Boolean result 

AND is intrinsic for CFT and CFT77. 

The following tables show both the logical product and bit-wise logical product; 



Logical Variable 1 


Logical Variable 2 


(Logical Variable 1) AND (Logical Variable 2) 


T 


T 


T 


T 


F 


F 


F 


T 


F 


F 


F 


F 



Bit of Variable 1 


Bit of Variable 2 


(Bit of Variable 1) AND (Bit of Variable 2) 


1 


1 


1 


1 


0 


0 


0 


1 


0 


0 


0 


0 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 
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CAUTIONS 

Unexpected results can occur when Boolean functions are declared external and then used with logical 
arguments. The external Boolean functions always treat their arguments as type Boolean and return a 
Boolean result. 

EXAMPLES 

The following section of Fortran code shows the AND function used with two arguments of type 
logical: 

LOGICAL LI, L2, L3 
L3 = AND(L1,L2) 

The following section of Fortran code shows the AND function used with two arguments of type 
integer. The bit patterns of the arguments and result are also given. For clarity, an 8-bit word is used 
instead of the actual 64-bit word. 

INTEGER II, 12, 13 

13 = AND(I1J2) 



0 


0 0 


0 


i i 


0 


0 


n 


0 


0 0 


0 


1 0 


1 


0 



12 



0 


0 


0 


0 


1 


0 


0 


0 



13 
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NAME 

ANINT, DNINT - Finds nearest whole number 

SYNOPSIS 

Fortran: 

r = ANTNT(real) 
d = DNJNT(double) 

DESCRIPTION 

These functions find the nearest whole number for real and double-precision numbers by using the fol- 
lowing equations: 

y = U+.5J if x >0 

y = L*-.sJ if x <o 

ANINT returns the real nearest whole number for its real argument. 

DNINT returns the double-precision nearest whole number for its double-precision argument. 

ANINT is the generic function name, 

ANINT and DNINT are intrinsic for CFT and CFI77. 

ARGUMENT RANGE 
ANINT: 

\x |<2 46 

DNINT: 
|x |<2 95 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 

Level of vectorization: Full 

Code generation: ANINT: In-line 
DNINT: External 
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NAME 



ASIN, DASIN, asin - Computes arcsine 
SYNOPSIS 

Fortran: 

r = ASSN{reaf) 
d = DASTN(double) 



C: 

finclude <math.h> 
double asin(x) 
double x; 



CAL register usage: 
Scalar ASIN: 

ASIN% (call by register) 
on entry (SI) = argument 
on exit (SI) - result 



Vector ASIN: 

%ASIN% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 



Scalar DASIN: 

DASIN% (call by register) 

on entry (SI) and (S2) - argument 

on exit (SI) and (S2) = result 



Vector DASIN: 

%DASIN% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) result vector 



DESCRIPTION 

These functions evaluate y = arcsin(;t). 

ASIN and asin (callable only from C programs) return the real arcsine of their real argument. 
DASIN returns the double-precision arcsine of its double-precision argument. 

ASIN is the generic function name. 

ASIN and DASIN are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

[ jc |^ 1.0 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 
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ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 



AT AN, DATAN, atan - Computes arctangent for single argument 
SYNOPSIS 



Fortran: 

r = ATAN(reaZ) 
d = DATAN(double) 



C: 

♦include <math.h> 
double atan(x) 
double x; 



CAL register usage: 
Scalar ATAN: 

ATAN% (call by register) 
on entry (SI) = argument 
on exit (SI) = result 



Vector ATAN: 

%ATAN% (call by register) 

on entry (VI) - argument vector 

cm exit (VI) = result vector 



Scalar DATAN: 

DATAN% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector DATAN: 

%DATAN% (call by register) 

on entry (VI) and (V2) - argument vector 

on exit (VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate y = arctan(*). 

ATAN and atan (callable only from C programs) return the real arctangent of their real argument. 
DATAN returns the double-precision arctangent of its double-precision argument. 

ATAN is the generic function name. 

ATAN and DATAN are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

|jt|<oo (oo=:l6*«) 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 
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ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 



SR-0113 



2-23 



D 



ATAN2(3M) 



ATAN2(3M) 



NAME 

ATAN2, DATAN2, atan2 - Computes arctangent for two arguments 
SYNOPSIS 



Fortran: 

r = ATAN2(rea/,rea/) 

d = DAT AN2(doubte>doubte) 



C: 

♦include <math.h> 
double atan2(xl»x2) 
double xl>x2; 



CAL register usage: 

Scalar ATAN2: 

ATAN2% (call by register) 
on entry (SI) - argument 1 
(S2) = argument 2 
on exit (SI) = result 



Vector ATAN2: 

%ATAN2% (call by register) 
on entry (VI) «= argument vector 1 
(V2) = argument vector 2 
on exit (VI) = result vector 



Scalar DATAN2: 

DATAN2% (call by register) 
on entry (SI) and (S2) = argument 1 
(S3) and (S4) - argument 2 
on exit (SI) and (S2) = result 



Vector DATAN2; 

%DATAN2% (call by register) 
on entry (VI) and (V2) argument vector 1 
(V3) and (V4) * argument vector 2 
on exit (VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate 

y - arctan(xi/jt2). 

ATAN2 and atan2 (callable only from C programs) return the real arctangent of the quotient of their 
real arguments. 

DATAN2 returns the double-precision arctangent of the quotient of its double-precision arguments. 

ATAN2 is the generic function name. 

ATAN2 and DATAN2 are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

l*iU*2l<°°> Uil l*2l are not both zero. (oo-lO 2466 ) 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 

C: 

ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 

CHAR, ICHAR - Converts integer to character and vice versa (Cray Fortran intrinsic function) 

SYNOPSIS 

ch=CHAR(integer) 
ch=CHAR(boolean) 

i=ICHAR(char) 
DESCRIPTION 

CHAR (inline Fortran code) and ICHAR are inverse functions. CHAR (type character) converts an 
integer or Boolean argument to a character specified by the ASCII collating sequence. Type conversion 
routines assign the appropriate type to Boolean arguments without shifting or manipulating the bit pat- 
terns they represent For example, CHAR(i) returns the *th character in the collating sequence, integer 
must be in the range 0 to 255. 

ICHAR (type integer) converts a character to an integer based on the character position in the collating 
sequence. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

CMPLX - Converts to type complex 

SYNOPSIS 

Fortran: 

c = CMPhX(ar gl [ 7 ar g2 l) 
DESCRIPTION 

This function converts one or two arguments into type complex. 
Complex and 24-bit integer arguments use a single argument. 

Integer, Boolean, real, and double-precision arguments can use either one or two arguments. 

Type conversion routines assign the appropriate type to Boolean arguments without shifting or manipu- 
lating the bit patterns they represent 

If two arguments are used, they must be of the same type. 

The following cases represent the evaluation of CMPLX when using two arguments: 

CMPLX(IJ) gives the value FLOAT(I)+i*FLOAT(J) 
CMPLX(x,y) gives the complex value x+i*y 

The following cases represent the evaluation of CMPLX when using one argument: 

CMPLX(X) gives the value X+i*0 
CMPLX(I) gives the value FLOAT(I)+i*0 

CMPLX (C) where C is a complex number, gives the complex value x+i*y; that is, 
CMPLX(C)=C. 

CMPLX is intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

Complex, real, double precision: 

|x|<oo (00= if) 2466 ) 

Integer: 
\x |<2* 

Integer (24-bit) (CFT only): 

I* |<2 23 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: In-line 
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NAME 

COMPL - Computes logical complement 

SYNOPSIS 

Fortran: 

/ = COMPUlogical) 
b = COMPL(arg) 

DESCRIPTION 

org = CFT: type Boolean, integer, or real 

CFT77: type Boolean, integer, real, or pointer 

When given an argument of type logical, COMPL computes a logical complement and returns a logical 
result 

When given an argument of type integer, real, Boolean, or pointer, COMPL computes a bit-wise logical 
complement and returns a Boolean result. 

COMPL is intrinsic for CFT and CFT77. 

The following tables show both the logical complement and bit-wise logical complement: 



Logical Variable 


COMPL (Logical Variable) 


T 


F 


F 


T 



Bit of Variable 


COMPL (Bit of Variable) 


1 


0 


0 


1 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 

CAUTIONS 

Unexpected results can occur when Boolean functions are declared external and then used with logical 
arguments. The external Boolean functions always treat their arguments as type Boolean and return a 
Boolean result. 
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EXAMPLES 

The following section of Fortran code shows the COMPL function used with an argument of type 
logical: 

LOGICAL LI, L2 
L2 = COMPL(Ll) 

The following section of Fortran code shows the COMPL function used with an argument of type 
integer. The bit patterns of the argument and result are also given. For clarity, an 8-bit word is used 
instead of the actual 64-bit word. 

INTEGER II, 12 

12 « COMPL(Il) 



1 1 1 


1 


1 


0 


0 


0 


0 


11 


0 


0 


0 


0 


1 


1 


1 


1 



12 
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NAME 

CONJG - Computes conjugate of a complex number 

SYNOPSIS 

Fortran: 

z = CONJG(a>mpfejt) 

DESCRIPTION 

This function evaluates 

y =x z -i * *j. 

CONJG returns the complex conjugate of a complex number. 
CONJG is intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

jx r |.|x,|<~ (»=lO 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: In-line 

EXAMPLE 

PROGRAM CONTEST 

COMPLEX ARG, RESULT 

ARG=(3.0,4.0) 

RESULT=CONJG(ARG) 

PRINT * .RESULT 

STOP 

END 

The preceding program gives RESULT = (3.,-4.)- 
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NAME 



COS, DCOS, CCOS, cos - Computes cosine 

SYNOPSIS 

Fortran: 

r = COS(reaO 
d = DCOS(doubte) 
z = CCOS(complex) 



C: 

#include <math.h> 
double cos(x) 
double x; 



CAL register usage: 
Scalar COS: 

COS% (call by register) 
on entry (SI) = argument 
on exit (SI) = result 



Vector COS: 

%COS% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 



Scalar DCOS: 

DCOS% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector DCOS: 

%DCOS% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



Scalar CCOS: 

CCOS% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector CCOS: 

%CCOS% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) - result vector 



DESCRIPTION 

These functions evaluate y = cos(x). 

COS and cos (callable only from C programs) return the real cosine of their real argument 
DCOS returns the double-precision cosine of its double-precision argument. 
CCOS returns the complex cosine of its complex argument 

COS is the generic function name. 

COS, DCOS, and CCOS am intrinsic for CFT and CFT77. 
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ARGUMENT RANGE 

COS: 

|x |<2 24 

DCOS: 
\x \<2? 

CCOS: 

|jt r |< 2 24 , | Xi J < 2 13 * ln2 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 

C: 

ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 

COSH, DCOSH, cosh - Computes hyperbolic cosine 
SYNOPSIS 

Fortran: 

r = COSH(reoO 
d = DCOSH(double) 

CAL register usage: 
Scalar COSH: 

COSH% (call by register) 
on entry (SI) - argument 
on exit (SI) - result 

Scalar DCOSH: 

DCOSH% (call by register) 
on entry (SI) and (S2) = argument 
on exit (SI) and (S2) = result 

DESCRIPTION 

These functions evaluate y = cosh(x). 

COSH and cosh (callable only from C programs) return the real hyperbolic cosine of their real argu- 
ment. 

DCOSH returns the double-precision hyperbolic cosine of its double-precision argument. 

COSH is the generic function name. 

COSH and DCOSH are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

|x |<2 13 * ln2 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 



tinclude <math.h> 
double cosh(x) 
double x; 



Vector COSH: 



%COSH% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 

Vector DCOSH: 

% DCOSH % (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 
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ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 

COT, DCOT - Computes cotangent 

SYNOPSIS 

Fortran: 

r = COT(reat) 

d * DCOT(<fcttWe) 



CAL register usage: 
Scalar COT: 

COT% (call by register) 
on entry (SI) = argument 
on exit (SI) = result 



Vector COT: 

%COT% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 



Scalar DCOT: 

DCOT% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector DCOT: 

%DCOT% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) - result vector 



DESCRIPTION 

These functions evaluate y - cot(x). 

COT returns the real cotangent of its teal argument. 

DCOT returns the double-precision cotangent of its double-precision argument 

COT is the generic function name. 

COT and DCOT are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 
M<2 24 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: External 
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NAME 

DASS, DASV, DAVS, DAW, DDSS, DDSV, DDVS, DDVV, DMSS, DMSV, DMVS, DMVV, DSSS, DSSV, 
DSVS f DSVV - Performs double-precision arithmetic 



DESCRIPTION 

Double-precision arithmetic routines include addition (D+D), division (D/D), multiplication (D*D), and 
subtraction (D-D) functions. These routines are implicitly called by CFT and CFT77 programs to per- 
form double-precision arithmetic. 



The function of each routine follows: 

BASS - Double-precision addition: Scalar + Scalar 

DASV - Double-precision addition: Scalar + Vector 

DAVS - Double-precision addition: Vector + Scalar 

DAW - Double-precision addition: Vector + Vector 

DDSS - Double-precision division: Scalar / Scalar 

DDSV - Double-precision division: Scalar / Vector 

DDVS - Double-precision division: Vector / Scalar 

DDVV - Double-precision division: Vector / Vector 

DMSS - Double-precision multiplication: Scalar * Scalar 

DMSV - Double-precision multiplication: Scalar * Vector 

DMVS - Double-precision multiplication: Vector * Scalar 

DMVV - Double-precision multiplication: Vector * Vector 

DSSS - Double-precision subtraction: Scalar - Scalar 

DSSV - Double-precision subtraction: Scalar - Vector 

DSVS - Double-precision subtraction: Vector - Scalar 

DSVV - Double-precision subtraction: Vector - Vector 



CAL REGISTER USAGE 

Double-precision addition: Scalar + Scalar 

DASS% (call by register) 
entry (SI) and (S2) = arg 1 words 1 and 2 
(S3) and (S4) * arg 2 words 1 and 2 
exit (SI) and (S2) = result words 1 and 2 



Double-precision addition: Scalar + Vector 

DASV% (call by register) 
entry (SI) and (S2) = arg 1 (augend) 
(V3) and (V4) = arg 2 (addend) 
exit (VI) and (V2) = result vector (sum) 



Double-precision addition: Vector + Scalar 

DAVS% (call by register) 
entry (VI) and (V2) = arg 1 (augend) 
(S3) and (S4) = arg 2 (addend) 
exit (VI) and (V2) = result vector (sum) 



Double-precision addition: Vector + Vector 

DAVV% (call by register) 
entry (VI) and (V2) - arg 1 (augend) 
(V3) and (V4) = arg 2 (addend) 
exit (VI) and (V2) = result vector (sum) 



Double-precision division: Scalar / Scalar 

DDSS% (call by register) 

entry (SI) and (S2) = numerator words 1 and 2 

(S3) and (S4) =s divisor words 1 and 2 
exit (SI) and (S2) = quotient words 1 and 2 



Double-precision division: Scalar / Vector 

DDSV% (call by register) 

entry (SI) and (S2) = numerator words 1 and 2 

(V3) and (V4) = divisor words 1 and 2 
exit (VI) and (V2) - quotient words 1 and 2 
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Double-precision division: Vector / Scalar 

DDVS% (call by register) 

entry (VI) and (V2) * numerator words 1 and 2 

(S3) and (S4) = divisor words 1 and 2 
exit (VI) and (V2) = quotient words 1 and 2 



Double-precision division: Vector / Vector 

DDVV% (call by register) 

entry (VI) and (V2) - numerator words 1 and 2 

(V3) and (V4) = divisor words 1 and 2 
exit (VI) and (V2) = quotient words 1 and 2 



Double-precision multiplication: Scalar * Scalar 

DMSS% (call by register) 
entry (SI) and (S2) - arg 1 words 1 and 2 
(S3) and (S4) = arg 2 words 1 and 2 
exit (SI) and (S2) = result words 1 and 2 



Double-precision multiplication: Scalar * Vector 

DMSV% (call by register) 
entry (SI) and (S2) = arg 1 words 1 and 2 
(V3) and (V4) = arg 2 words 1 and 2 
exit (VI) and (V2) = product words 1 and 2 



Double-precision multiplication: Vector * Scalar 

DMVS% (call by register) 
entry (VI) and (V2) = arg 1 words 1 and 2 
(S3) and (S4) - arg 2 words 1 and 2 
exit (VI) and (V2) = product words 1 and 2 



Double-precision multiplication: Vector * Vector 

DMW% (call by register) 
entry (VI) and (V2) = arg 1 words 1 and 2 
(V3) and (V4) = arg 2 words 1 and 2 
exit (VI) and (V2) = product words 1 and 2 



Double-precision subtraction: Scalar - Scalar 

DSSS% (call by register) 
entry (SI) and (S2) = arg 1 words 1 and 2 
(S3) and (S4) = arg 2 words 1 and 2 
exit (SI) and (S2) = result words 1 and 2 



Double-precision subtraction: Scalar - Vector 

DSSV% (call by register) 

entry (SI) and (S2) - arg 1 (minuend) 

(V3) and (V4) = arg 2 (subtrahend) 
exit (VI) and (V2) = result vector (sum) 



Double-precision subtraction: Vector - Scalar 

DSVS% (call by register) 

entry (VI) and (V2) = arg 1 (minuend) 

(S3) and (S4) = arg 2 (subtrahend) 
exit (VI) and (V2) = result vector (sum) 



Double-precision subtraction: Vector - Vector 

DSW% (call by register) 

entry (VI) and (V2) = arg 1 (minuend) 

(V3) and (V4) = arg 2 (subtrahend) 
exit (VI) and (V2) = result vector (sum) 



IMPLEMENTATION 

These routines are available to users of both the COS and TJNICOS operating systems. 
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NAME 

DBLE, DFLOAT - Converts to type double precision 

SYNOPSIS 

Fortran: 

d = DRLE(arg) 

d = DFLOAT(integer) 

DESCRIPTION 

arg - type complex, integer, Boolean, real, or double precision 
These functions convert specified types to type double precision. 

DBLE returns the double-precision equivalent of its complex, integer, Boolean, real, or double-precision 
argument. 

DFLOAT returns the double-precision floating-point equivalent of its integer argument. 

Type conversion routines assign the appropriate type to Boolean arguments without shifting or manipu- 
lating the bit patterns they represent* 

ARGUMENT RANGE 
DBLE: 

Real, double precision, Boolean: 

| X | < oo (ooS 10 2466 ) 

Complex: 

| x t | < oo (for complex arguments jc = x T + i * x L ) 

Integer: 
j x | < 2 63 

Integer (24-bit) (CFT only): 
| x | < 2 23 

DFLOAT: 

|* |<2 63 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NOTES 

Fortran: 
DBLE: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: In-line 

DFLOAT: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 
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NAME 

DIM, IDIM, DDIM - Computes positive difference of two numbers 

SYNOPSIS 

Fortran: 

r = DTM(real t reaI) 

i = IDTM(integer integer) 

d = DDJM(double t doub!e) 

DESCRIPTION 

These functions solve for: 

y =*i -*2 if Xi >x 2 
y - 0 if x x < x 2 

DIM evaluates two real numbers and subtracts them. The result is a real positive difference. 

IDIM evaluates two integers and subtracts them. The result is an integer positive difference. 

DDIM evaluates two double-precision numbers and subtracts them. The result is a double-precision 

positive difference. 

DIM is the generic function name. 

DIM, IDIM, and DDIM are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

I *i I . I *2 1 < 00 (°° ~ 10 7466 ) Exception: IDIM far 64-bit integers: | *i [ , | x 2 \ < 2 63 
IMPLEMENTATION 

Ifcese routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 

Level of vectorization: Full 

Code generation: DIM, IDIM: In-line 
DDIM: External 
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EXAMPLE 



PROGRAM DIMTEST 
INTEGER A,B,C,D,E 
A=77 
B=10 

C=IDIM(A > B) 
WRITE 1,A,B,C 

1 FORMAT(I2,'POSITIVE DIFFERENCE '42,' EQUALS 12) 

D=IDIM(B,A) 
WRITE 2.BA.D 

2 FORMAT(I2,'POSrnVE DIFFERENCE ',12,* EQUALS ' ,12) 
STOP 

END 

The preceding program gives the following output: 

77 POSITIVE DIFFERENCE 10 EQUALS 67 
10 POSITIVE DIFFERENCE 77 EQUALS 0 
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NAME 

DPROD - Computes double-precision product of two real numbers 

SYNOPSIS 

Fortran: 

d = DPROD(rea/,rea/) 



CAL register usage: 

Scalar DPROD: 

DPROD % (call by register) 
entry (SI) = 1st argument (single precision) 
(S2) » 2nd argument (single precision) 
exit (SI) and (S2) = result words 1 and 2 



Vector DPROD: 

%DPROD% (call by register) 
entry (VI) = 1st argument (single precision) 
(V2) * 2nd argument (single precision) 
exit (VI) and (V2) - product words 1 and 2 



DESCRIPTION 

This function evaluates y - X\*x 2 . 

DPROD returns the double-precision product of its two real arguments, 
DPROD is intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

\Xx\.\x 2 \<» (oo^lO 2 **) 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 

EXAMPLE 



PROGRAM DOUBT 
REALX.Y 

DOUBLE PRECISION Z 

X=5.0 

Y=6.0 

Z=DPROD(X,Y) 
PRINT *,Z 
STOP 
END 



The preceding program gives Z to be the double-precision number 30.0 (or in Fortran, 30.D0). 
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NAME 

EQV - Computes logical equivalence 

SYNOPSIS 

Fortran: 

I = EQV(logicaUogical) 
b = EQV(arg.arg) 

DESCRIPTION 

org - CFT: type Boolean or integer 

CFT77: type Boolean, integer, real, or pointer 

When given two arguments of type logical, EQV computes a logical equivalence and returns a logical 
result. 

When given two arguments of type Boolean, real, integer, or pointer, EQV computes a bit-wise logical 
equivalence and returns a Boolean result 

EQV is intrinsic for CFT and CFT77. 

The following tables show both the logical equivalence and bit-wise logical equivalence: 



Logical Variable 1 


Logical Variable 2 


(Logical Variable 1) EQV (Logical Variable 2) 


T 


T 


T 


T 


F 


F 


F 


T 


F 


F 


F 


T 
















Bit of Variable 1 


Bit of Variable 2 


(Bit of Variable 1) EQV (Bit of Variable 2) 






1 


1 


1 






1 


0 


0 






0 


1 


0 






0 


0 


1 





IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 
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cautions 

Unexpected results can occur when Boolean functions are declared external and then used with logical 
arguments. The external Boolean functions always treat their arguments as type Boolean and return a 
Boolean result. 

EXAMPLES 

The following section of Fortran code shows the EQV function used with two arguments of type 
logical: 

LOGICAL LI, L2, L3 
L3 = EQV(L1JL2) 

The following section of Fortran code shows the EQV function used with two arguments of type 
integer. The bit patterns of the arguments and result are also given. For clarity, an 8-bit word is used 
instead of the actual 64-bit word. 

INTEGER II, 12, 13 

13 = EQV(I1,I2) 



|o 


0 


0 | 0 


1 


1 


0 


0 


11 


0 


0 


0 


0 


1 


0 


1 


0 


12 


1 


1 


1 


1 


1 


0 


0 


1 
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NAME 



EXP, DEXP, CEXP, exp - Computes exponential function 
SYNOPSIS 



Fortran: 

r = EX¥(real) 
d = DEKP(double) 
2 = CEXP(complex) 



# include <math.h> 
double exp(x) 
double x; 



CAL register usage: 
Scalar EXP: 

EXP% (call by register) 
on entry (SI) = argument 
on exit (SI) = result 

Scalar DEXP: 

DEXP% (call by register) 
on entry (SI) and (S2) = argument 
on exit (SI) and (S2) = result 

Scalar CEXP: 

CEXP% (call by register) 
on entry (SI) and (S2) - argument 
on exit (SI) and (S2) = result 

DESCRIPTION 

These functions evaluate y = e z . 

EXP and exp (callable only from C programs) return the real exponential function e* of their real argu- 
ment 

DEXP returns the double-precision exponential function e x of its double-precision argument. 
CEXP returns the complex exponential function e x of its complex argument. 

EXP is the generic function name. 

EXP, DEXP, and CEXP are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

EXP, DEXP: | x \ < 2 13 * In 2 
CEXP: \x T | < 2 13 * In 2 , \ Xi \ < 2™ 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 



Vector EXP: 

%EX?% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 

Vector DEXP: 

%DEXP% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) - result vector 

Vector CEXP: 

%CEXP% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 
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NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 

C: 

ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 

INDEX - Determines index location of a character substring within a string (Cray Fortran intrinsic func- 
tion) 

SYNOPSIS 

i=INDEX(string .substring) 

DESCRIPTION 

The integer function INDEX takes Fortran character string arguments and returns an integer index into 
that string. If substring is not located within string, a value of 0 is returned. If there is more than one 
occurrence of substring, only the first index is returned, string and substring can be any legal Fortran 
character string. 

EXAMPLE 



PROGRAM INDEX 1 
CHARACTER*23 r A 

CHARACTER* 133 

A='CRAY X-MP SUPERCOMPUTER' 

B=* SUPERCOMPUTER' 

I=INDEX(A,B) 

PRINT*, I 

STOP 

END 

The preceding program returns the index number of the substring SUPERCOMPUTER as 1=1 1. 



PROGRAM INDEX2 

CHARACTER*20A 

CHARACTER*63 

A='CRAY-1 SUPERCOMPUTER' 

B='CRAY-1* 

I=INDEX(A,B) 

PRINT M 

STOP 

END 

The preceding program returns the index number of the substring CRAY-1 as 1=1. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

INT, IFIX, IDINT - Converts to type integer 

SYNOPSIS 

Fortran: 

i = INT(ar#) 

i = IFlX(r^0 
i = IFlX(boolean) 

i = IDINT(d0id>te) 

DESCRIPTION 

org = type integer, complex, real, or Boolean 

These functions convert specified types to type integer by truncating toward 0 (the fraction is lost). 

INT returns an integer value for its integer, real, complex, or Boolean argument. 
IF1X returns an integer value for its real or Boolean argument. 
IDINT returns an integer value for its double-precision argument. 

INT is the generic function name. 

INT, IFIX, and IDINT are intrinsic for CFT and CFT77. 

Type conversion routines assign the appropriate type to Boolean arguments without shifting or manipu- 
lating the bit patterns they represent. 

ARGUMENT RANGE 
INT: 

Real: | x \ < ~ (*o = 10 2466 ) 
Complex: \x t \<2 46 
Integer (24-bit) (CFT only): \ x \ < 2 23 
Integer, Boolean: | x \ < 2 63 

IFIX: \x |<2^ 

IDINT: I x I < 2 63 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: In-line 
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NAME 

INT24, LINT - Converts 64-bit integer to 24-bit integer and vice versa (CFT only) 

SYNOPSIS 

Fortran: 

124 = IKT2A(int€ger) 
i24 = lNT24(boolean) 

i = LINT(24-Wf integer) 

DESCRIPTION 

i24 = 24-bit integer result. 

INT24 converts a 64-bit integer or Boolean argument into a 24-bit integer. 
LINT converts a 24-bit integer into a 64-bit integer. 

ARGUMENT RANGE 
|x|<2 23 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorizatton: Full 
Code generation: In-line 
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NAME 

LOSS, LDSV, LDVS, LOW - Performs 64-bit integer divide 
DESCRIPTION 

The LDSS, LDSV, LDVS, and LDVV functions are called implicitly by CFT, CFT77 > and C programs to 
divide long integers. 

These routines return a 64-bit integer quotient from two 64-bit arguments. 

The function of each routine follows: 
LDSS - Scalar / Scalar 
LDSV - Scalar / Vector 
LDVS - Vector / Scalar 
LDVV - Vector / Vector 

CAL REGISTER USAGE 



Scalar / Scalar: 

LDSS% (call by register) 
on entry (Si) - numerator 

(S2) = denominator 
on exit (SI) = quotient 

(S2) - remainder 



Scalar / Vector: 

LDSV% (call by register) 
on entry (SI) = numerator 

(V2) = denominator 
on exit (VI) = quotient 

(V2) = remainder 



Vector / Scalar: 

LDVS % (call by register) 
on entry (VI) = numerator 

(S2) = denominator 
on exit (VI) = quotient 

(V2) = remainder 



Vector / Vector: 

LDVV% (call by register) 
on entry (VI) = numerator 

(V2) = denominator 
on exit (VI) = quotient 

(V2) - remainder 



NOTE 

LDSV, LDVS, and LDVV are pseudo-vector routines. They call the scalar version, LDSS, to perform the 
divide. 
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NAME 

LEADZ - Counts number of leading 0 bits 

SYNOPSIS 

Fortran: 

i = LEADZ(ar$) 

DESCRIPTION 

arg = CFT: type Boolean, integer, real, or logical 
CFT77: type Boolean, integer, real, or pointer 

When given an argument of type integer, real, logical, Boolean, or pointer, LEADZ counts the number 
of leading 0 bits in the 64-bit representation of the argument 

LEADZ is intrinsic for CFT and CFT77. 
EXAMPLES 

The following section of Fortran code shows the LEADZ function used with an argument of type 
integer. The bit pattern of the argument and the value of the result are also given. For clarity, a 16-bit 
word is used instead of the actual 64-bit word, 

INTEGER II, 12 

12 = LEADZ(I1) 



0 1 0 
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0 


1 


I 


1 


0 


0 


1 


0 



II 



The LEADZ function returns the value 5 to the integer variable 12. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems, 

NOTES 

The bit representation of the logical data type is not consistent among Cray machines. For further 
details, see the Fortran (CFT) Reference Manual, publication SR-0009, and the CFT77 Reference Manual, 
publication SR-0018. 

LEADZ(O) is equal to 64. 
Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 
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NAME 

LEN - Determines the length of a character string (Cray Fortran intrinsic function) 

SYNOPSIS 

i = LEN(string) 

DESCRIPTION 

The integer function LEN takes Fortran character string arguments and returns an integer length, string 
can be any valid Fortran character string. LEN is an in-line code function. 

EXAMPLE 

PROGRAM LENTEST 

I=LEN( , l...+....l.,..+...5....+....3....+.. , ) 

PRINT *I 

STOP 

END 

The preceding program returns the length of the character siring; 1=37. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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LGE, LGT, LLE, LLT - Compares strings lexically (Cray Fortran intrinsic function) 

SYNOPSIS 

/ = LGE(stringljtring2) 
I = LGT(stringl t string2) 
I - LLE($tringl .string!) 
I = hVT(stringl t string2) 

DESCRIPTION 

Each of the these type logical functions takes two character string arguments and return a logical value. 
stringl and string! are compared according to the ASCII collating sequence, and the resulting true or 
false value is returned. Arguments can be any valid character string. If the strings are of different 
lengths, the function treats the shorter string as though it were blank-filled on the right to the length of 
the longer string. 

The defining equation for each function is as follows: 



For LGE, logic 
For LGT, logic 
For LLE, logic 
For LLT, logic 



a x <a 2 . 



IMPLEMENTATION 



These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

MASK - Returns a bit mask 

SYNOPSIS 

Fortran: 

b = MASK(integer) 

DESCRIPTION 

MASK returns a bit mask of Vs. 

The integer argument must be in the range 0 < x < 128. 

If the argument is in the range 0 < x ^ 63, a left-justified mask of x bits is returned. 

If the argument is in the range 64 < x ^ 128, a right-justified mask of (128 - x) bits is returned. 

MASK is intrinsic for CFT and CFT77. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 

EXAMPLES 

The following section of Fortran code shows the MASK function used with several different arguments. 
The bit patterns of the results are given. The 64-bit word has been shortened to improve clarity. 

INTEGER II, 12, 13 

11 = MASK(3) 

12 = MASK(64) 

13 = MASK(127) 
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NAME 

MOD, AMOD, DMOD ~ Computes remainder of X\lx 2 

SYNOPSIS 

Fortran: 

i = MODQntegerjnteger) 

r - AMOD(real,reaf) 

d = DMOD(double.double) 

DESCRIPTION 

These functions evaluate y = x x -x 2 [xiix 2 ^ • 

MOD returns the integer remainder of its integer arguments. 

AMOD returns the real remainder of its real arguments. 

DMOD returns the double-precision remainder of its double-precision arguments. 

MOD is the generic function name. 

MOD, AMOD, and DMOD are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 
MOD: 

l*i I <2 63 
0<|* 2 |<2 63 
2-™ <\x 1 /x 2 \<2 63 

AMOD: 

Uil<2 47 
0<|* 2 |<2 47 
2- 41 <\x l /x 2 \<2 41 

DMOD: 

|je!|<2 95 

0<|* 2 |<2 95 

2-* 5 <|jc 1 /jc 2 |<2 m 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 

Level of vectorization: Full 

Code generation: MOD, AMOD: In-line 

DMOD, MOD (long integer - CFT only): External 



SR-0113 



D 



NEQV(3M) 



NEQV(SM) 



NAME 

NEQV, XOR - Computes logical difference 

SYNOPSIS 

Fortran: 

/ = NEQy(logicaUogicaT) 
I = XOR(logical .logical) 

b = NEQV(arg t arg) 
b = XOR(arg,arg) 

DESCRIPTION 

org = CFT: type Boolean, integer, or real 

CFT77; type Boolean, integer, real, or pointer 

NEQV and XOR are two names for the same routine. 

When given two arguments of type logical, NEQV and XOR compute a logical difference and return a 
logical result. 

When given two arguments of type Boolean, integer, Teal, or pointer, NEQV and XOR compute a bit- 
wise logical difference and return a Boolean result. 

NEQV and XOR are intrinsic for CFT and CFT77. 

The following tables show both the logical difference and bit-wise logical difference. 
NEQV is shown in the tables, but XOR produces identical results. 



Logical Variable 1 


Logical Variable 2 


(Logical Variable 1) NEQV (Logical Variable 2) 


T 


T 


F 


T 


F 


T 


F 


T 


T 


F 


F 


F 
















Bit of Variable 1 


Bit of Variable 2 


(Bit of Variable 1) NEQV (Bit of Variable 2) 






I 


1 


0 






1 


0 


1 






0 


1 


1 






0 


0 


0 





IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 

CAUTIONS 

Unexpected results can occur when Boolean functions are declared external and then used with logical 
arguments. The external Boolean functions always treat their arguments as type Boolean and return a 
Boolean result 

EXAMPLES 

The following section of Fortran code shows the NEQV function used with two arguments of type 
logical- XOR is used in the same manner and produces the same results. 

LOGICAL LI, L2,L3 

L3 = NEQV(L1JL2) 

The following section of Fortran code shows the NEQV function used with two arguments of type 
integer, XOR is used in the same manner and produces the same results. 

The bit patterns of the arguments and result are also given. For clarity, an 8-bit word is used instead of 
the actual 64-bit word. 

INTEGER II, 12, 13 

13 = NEQV(I1,I2) 
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NAME 

NINT, IDNINT - Finds nearest integer 

SYNOPSIS 

Fortran: 

i - NINT(rea/) 

i = IDNTNT(doubIe) 

DESCRIPTION 

These functions find the nearest integer for real and double-precision numbers, using the following 
equations: 

y = [x+.Sj if x >0 

y - U~5j if x <0 

NINT returns the nearest integer for its real argument 

IDNINT returns the nearest integer for its double-precision argument. 

NINT is the generic function name. 

NINT and IDNINT are intrinsic for CFT and CFT77, 

ARGUMENT RANGE 

\x \<2" 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 

Level of vectorization: Full 

Code generation: NINT: In-line 

IDNINT: External 
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NAME 

OR - Computes logical sum 

SYNOPSIS 

Fortran: 

/ = OR{logicaUlogicat) 
b = OR(arg t arg) 

DESCRIPTION 

arg = CFT: type Boolean, integer, or real 

CFT77: type Boolean, integer, real, or pointer 

When given two arguments of type logical, OR computes a logical sum and returns a logical result 
When given two arguments of type integer, real, Boolean, or pointer, OR computes a bit-wise logical 
sum and returns a Boolean result 

OR is intrinsic for CFT and CFT77. 

The following tables show both the logical sum and bit- wise logical sum: 



Logical Variable 1 


Logical Variable 2 


(Logical Variable 1) OR (Logical Variable 2) 
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Bit of Variable 1 


Bit of Variable 2 


(Bit of Variable 1) OR (Bit of Variable 2) 
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0 


0 


0 





IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 
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CAUTIONS 

Unexpected results can occur when Boolean functions are declared external and then used with logical 
arguments. The external Boolean functions always treat their arguments as type Boolean and return a 
Boolean result. 

EXAMPLES 

The following section of Fortran code shows the OR function used with two arguments of type logical: 
LOGICAL LI, L2, L3 
L3 =OR(Ll,L2) 

The following section of Fortran code shows the OR function used with two arguments of type integer. 
The bit patterns of the arguments and result are also shown below. For clarity, an 8~bit word is used 
instead of the actual 64-bit word, 

INTEGER II, 12, 13 

13 - OR(Il t I2) 
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NAME 

POPCNT - Counts number of bits set to 1 

SYNOPSIS 

Fortran: 

/ = POPCNT(ar£) 

DESCRIPTION 

arg = CFT: type Boolean, integer, real, or logical 
CFT77: type Boolean, integer, real, or pointer 

When given an argument of type integer, real, logical, Boolean, or pointer, POPCNT counts the number 
of bits set to 1 in the 64-bit representation of the argument. 

POPCNT is intrinsic for CFT and CFI77, 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

The bit representation of the logical data type is not consistent among Cray machines. For further 
details, see the Fortran (CFT) Reference Manual, publication SR-0009, and the CFT77 Reference Manual, 
publication SR-0018. 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 

EXAMPLES 

The following section of Fortran code shows the POPCNT function used with an argument of type 
integer. The bit pattern of the argument and the value of the result are also given. For clarity, a 16-bit 
word is used instead of the actual 64-bit word. 

INTEGER II, 12 

12 = POPCNT(Il) 
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0 1 0 



0 0 



II 



The POPCNT function returns the value 6 to the integer variable 12. 
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NAME 

POPPAR - Computes bit population parity 

SYNOPSIS 

Fortran: 

i = POPPAR(ar 5 ) 

DESCRIPTION 

arg = CFT: type Boolean, integer, real, or logical 
CFT77: type Boolean, integer, real, or pointer 

When given an argument of type integer, real, logical, Boolean, or pointer, POPPAR returns the value 0 
if an even number of bits are set to 1 in the 64-bit representation of the argument or the value 1 if an 
odd number of bits are set to 1 in the 64-bit representation of the argument 

POPPAR is intrinsic for CFT and CFT77. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

The bit representation of the logical data type is not consistent among Cray machines. For further 
details, see the Fortran (CFT) Reference Manual, publication SR-0009, and the CFT77 Reference Manual, 
publication SR-0018. 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 

EXAMPLES 

The following section of Fortran code shows the POPPAR function used with an argument of type 
integer. The bit pattern of the argument and the value of the result are also given. For clarity, a 16-bit 
word is used instead of the actual 64-bit word. 

INTEGER II, 12 

12 » POPPAR(Il) 
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The POPPAR function returns the value 0 to the integer variable 12. 
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NAME 

CTOC, CTOI, CTOR, DTOD, DTOI, DTOR, ITOI, RTOI, RTOR, pow - Raises base value to a power 

SYNOPSIS 

C: 

#include <mathJi> 

double pow(x, y) 
double x, y; 

DESCRIPTION 

These routines return the appropriate real or integer power function X Y of their arguments. 

CFT and CFT77 routines implicitly call these routines to raise a value to a power. 

CTOC, CTOI, and CTOR raise a complex base to a complex power (C c ), an integer power (C 7 ), or a 

real power (C R ), respectively. 

The complex base cannot be (0.0, 0.0). 

DTOD, DTOI, and DTOR raise a double-precision base to a double-precision power (D D ) y an integer 
power (D ; ), or a real power (£>*), respectively. 

ITOI raises an integer base to an integer power (I 1 ). 

RTOI and RTOR raise a real base to an integer power (R 1 ) or a real power (R R ), respectively. 
Routine pow raises a real base to a real power (/?*). 
Base values in DTOD, DTOR, and RTOR must be positive. 
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NAME 

RANF, RANGET, RANSET - Computes pseudo-random numbers 

SYNOPSIS 

Fortran: 

r = RANF( ) 

b = RANGET(integer) (CFT) 
b = RANGET([wte$erj) (CFT77) 

r = RANSET(integer) (CFT) 
r = RANSET(<arg) (CFT77) 

DESCRIPTION 

org = type integer, real, or Boolean 

These functions compute pseudo-random numbers and either set or retrieve a seed. 
RANF: 

• Obtains the first or next in a series of pseudo-random numbers, such that 0 < y < 1, in the form of 
a normalized floating-point number. 

• Uses a null argument. If an argument is supplied, it will be ignored. Parentheses are required in 
the call, however. 

RANGET: 

• Obtains a seed. 

• Can be called as a function or a subroutine in CFT. 

• Has an optional integer argument for CFT77. 

• Requires an integer argument for CFT. 

If an argument is present, the result is also returned at the address of the argument. 
RANSET: 

• Establishes a seed such that y = x. 

• Requires an integer argument in CFT. 

• Requires an argument of type integer, real, or Boolean in CFT77. 

The return value of the function is not meaningful (it returns the input value). 

If no argument or a zero argument is supplied, the seed is reset to an initial default value. 

If an argument is supplied, the lower 48 bits are used as the random-number seed. The right-most bit 
is always set to 1. 

When the seed of the random number generator is reset, RANSET does not store the supplied argu- 
ment as the first value in the buffer of the random number seeds. 

RANF, RANGET, and RANSET are intrinsic for CFT and CFT77, 
ARGUMENT RANGE 



\x\< 
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IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 

Level of vectorization: RANF: Full 

RANGET, RANSET: None 

Code generation: External 

The CRI random number generator uses static memory storage for the random number seed table. 
Therefore, the functions RANF, RANSET, and RANGET must be protected (locked) when called from a 
multitasked program. 



EXAMPLES 



00101=1,10 
10 RANDOM(I)=RANF( ) 



CALL RANGKT(iseedl) 
or 

iseed=RANGET(ivati4e) 



CALL RANSETQvalue) 
or 

dummy=RANSET(ivatue) 
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NAME 

REAL, FLOAT, SNGL - Converts to type real 

SYNOPSIS 

Fortran: 

r = REAL(or&) 

r = ¥LOXT(integer) 

r = SNGUdouble) 
r = SNGhibootean) 

DESCRIPTION 

arg = type complex, integer, or real 

These functions convert specified types to type real, such that y * x (or y =x T for complex arguments). 

REAL returns the real equivalent of its complex, integer, or real argument. 

FLOAT returns the real equivalent of its integer argument 

SNGL returns the real equivalent of its double-precision or Boolean argument. 

Type conversion routines assign the appropriate type to Boolean arguments without shifting or manipu- 
lating the bit patterns they represent. 

REAL is the generic function name. 

REAL, FLOAT, and SNGL are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 
REAL: 

Real: \x\<<*> (~ ^ itf"*) 
Integer \x\<2^ 
Complex: | x t \ < «>) 

FLOAT: 

Integer: \x\<2 63 

OA-bit integer (CFT only): | x \ < I 23 

SNGL: 

Double precision: | x | < °o (in CFT 77, | x | < 2 M ) 
Boolean: |x|<2 46 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: In-line 
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NAME 

SfflFT - Performs a left circular shift 

SYNOPSIS 

Fortran: 

b = SHlFT(argl ,arg2) 

DESCRIPTION 

argl = The value to be shifted 

CFT77: type Boolean, integer, real, or pointer 
CFT: type Boolean, integer, or real 

arg2 - The number of bits to shift the value 
- type integer 

For argl in the range 0 < argl < 64, SHIFT performs a left circular shift of the 64-bit representation of 
argl by argl bits. 

For argl £ 65, a left circular shift is not performed. Instead, SHIFT is defined as follows when 
argl £ 65: 

For argl in the range 65 < argl < 128, SHIFT (argJ ,arg2) is defined as smFYL(argl,arg2~64). 
See SMFTL(3M). 

For argl in the range 129 < argl < 2 24 -l, SHIFT returns a value with all bits set to 0. 
For argl in the range 2^ < argl < 2 64 -l, SHIFT returns an undefined result 
SHIFT is intrinsic for CFT and CFT77. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

The bit representation of the logical data type is not consistent among Cray machines. For further 
details, see the Fortran (CFT) Reference Manual, publication SR-0009, and the CFT77 Reference Manual, 
publication SR-0018. 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 
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EXAMPLES 

The following section of Fortran code shows the SHIFT function used in the case where argl is of type 
integer. For purposes of clarity, a 16-bit word is used instead of the actual 64-bit word. The bit pattern 
of argl and the bit pattern of the result are also given. 

INTEGER II, 12, 13 

12 = 5 

13 = SHIFT(I1,I2) 
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NAME 

SfflFTL - Performs a left shift with zero fill 

SYNOPSIS 

Fortran: 

b = SmFTL(argl,arg2) 

DESCRIPTION 

argl = The value to be shifted 

CFT77: type Boolean, integer, real, or pointer 
CFT: type Boolean, integer, or real 

argl - The number of bits to shift the value 
- type integer 

For argl in the range 0 < argl £ 2 24 -l, SHIFTL performs a left shift with zero fill of the 64-bit 
representation of argl by argl bits. Note that when argl is in the range 64 <, argl <x 2 24 -l, SHIFTL 
returns a value with all bits set to 0. 

For argl in the range 2^ < argl < 2 64 -l , SHIFTL returns an undefined result 
SHIFTL is intrinsic for CFT and CFT77. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

The bit representation of the logical data type is not consistent among Cray machines. For further 
details, see the Fortran (CFT) Reference Manual, publication SR-0009, and the CFT77 Reference Manual, 
publication SR-0018. 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation; In-line 
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EXAMPLES 

The following section of Fortran code shows the SHJFTL function used in the case where argl is of 
type integer. The bit pattern of argl and the bit pattern of the result are also given. For clarity, a 16- 
bit value is used instead of a 64-bit value. 

INTEGER II, 12, 13 

12 = 5 

13 = SHTFTL(I1,I2) 
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NAME 

SHIFTR - Performs a right shift with zero fill 

SYNOPSIS 

Fortran: 

b = SHlFTR(argl t arg2) 

DESCRIPTION 

argl = The value to be shifted 

CFT77: type Boolean, integer, real, or pointer 
CFT: type Boolean, integer, or real 

arg2 - The number of bits to shift the value 
- type integer 

For argl in the range 0 < argl £ 2 24 -l, SHIFTR performs a right shift with zero fill of the 64-bit 
representation of argl by argl bits. Note that when argl is in the range 64 <; argl £ 2 24 -l, SHIFTR 
returns a value with all bits set to 0. 

For argl in the range 2 M < argl < 2 64 -l, SHIFTR returns an undefined result. 
SHIFTR is intrinsic for CFT and CFT77. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

The bit representation of the logical data type is not consistent among Cray machines. For further 
details, see the Fortran (CFT) Reference Manual, publication SR-0009, and the CFT77 Reference Manual, 
publication SR-0018. 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: Cray extension 
Level of vectorization: Full 
Code generation: In-line 
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EXAMPLES 

The following section of Fortran code shows the SHIFTR function used in the case where argl is of 
type integer. The bit pattern of argl and the bit pattern of the result are also given. For purposes of 
clarity, a 16-bit value is used instead of a 64-bit value. 

INTEGER II, 12, 13 

12 = 5 

13 = SHIFTR(I142) 
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NAME 

SIGN, ISIGN, DSIGN - Transfers sign of numbers 

SYNOPSIS 

Fortran: 

r = SlGN(real,reat) 

i - l$\GN(integer integer) 

d = VSIGVi(double f cL>uble) 

DESCRIPTION 

This function evaluates one of the following equations* depending on the sign of the number: 

y = \xi \ if x 2 >0 
or 

y tf *2<0 

SIGN transfers the sign from one real number to another. 

ISIGN transfers the sign from one integer to another. 

DSIGN transfers the sign from one double-precision number to another. 

SIGN is the generic function name. 

SIGN, ISIGN, and DSIGN are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

!*iU*2l<~ (~-io*<*) 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: In-line 
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NAME 

SIN, DSIN, CSIN, sin - Computes the sine 

SYNOPSIS 

Fortran: 

r = STN(real) 

d = DSlN(doubte) 

z = CSIN(complex) 



♦include <math.h> 
double sin(x) 
doable x; 



CAL register usage: 
Scalar SIN: 

SIN% (call by register) 
on entry (SI) « argument 
on exit (SI) = result 



Vector SIN: 

%SIN% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 



Scalar DSIN: 

DSIN% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector DSIN: 

%DSIN% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



Scalar CSIN: Vector CSIN: 

CSm% (call by register) %CSIN% 

on entry (SI) and (S2) = argument on entry 

on exit (SI) and (S2) = result on exit 



(call by register) 

(VI) and (V2) = argument vector 
(VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate y = sin(*). 

SIN and sin (callable only from C programs) return the real sine of their real arguments. 
DSIN returns the double-precision sine of its double-precision argument. 
CSIN returns the complex sine of its complex argument 

SIN is the generic function name. 

SIN, DSIN, and CSIN are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 
SIN: | x | < 2 W 
DSIN: | x | < 2 4 * 

CSIN: \x x |< 2 24 , Ijq |<2 13 * ln2 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 

C: 

ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 



SINE, DSINH, sinh - Computes hyperbolic sine 



SYNOPSIS 



Fortran: 



C: 



r = SINH(rea/) 
d = DS1NH(double) 



double sinh(x) 
double x; 



finclude <math.h> 



CAL register usage: 



Scalar SINH: 



Vector SINH: 



SINH% (call by register) 
on entry (SI) = argument 
on exit (SI) = result 



%SINH% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 



Scalar DSINH: 



Vector DSINH: 



DSINH% 
on entry 
on exit 



(call by register) 

(SI) and (S2) = argument 

(SI) and (S2) = result 



% DSINH % (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate y » sinh(x). 

SINH and sinh (callable only from C programs) return the real hyperbolic sine of their real argument 
DSINH returns the double-precision hyperbolic sine of its double-precision argument. 

SINH is the generic function name. 

SINH and DSINH are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

|x |<2 13 * ln2 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 
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ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 

SNGLR - Returns closest real approximation to double precision 

SYNOPSIS 

Fortran: 

r = SNGLROfow&fe) 
DESCRIPTION 

SNGLR returns the closest real approximation to its double-piecision argument. 

The double-precision argument is rounded to a single word, using the high-order bit of the second word. 
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NAME 



SQRT, DSQRT, CSQRT, sqrt - Computes square root 
SYNOPSIS 



Fortran: 

r = SQRT(rea/) 
d = DSQRT(double) 
2 = CSQRT(complex) 



C: 

#include <rnath.h> 
double sqrt(x) 
double x; 



CAL register usage: 
Scalar SQRT: 

SQRT% (call by register) 
on entry (SI) = argument 
on exit (SI) = result 



Vector SQRT: 

%SQRT% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 



Scalar DSQRT: 

DSQRT % (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector DSQRT: 

% DSQRT % (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



Scalar CSQRT: 

CSQRT% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) = result 



Vector CSQRT: 

% CSQRT % (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate y =x l/2 . 

SQRT and sqrt (callable only from C programs) return the real square root of their real argument. 
DSQRT returns the double-precision square root of its double-precision argument. 
CSQRT returns the complex square root of its complex argument 

SQRT is the generic function name. 

SQRT, DSQRT, and CSQRT are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

SQRT, DSQRT: 0 < x < *> (002 10 2466 ) 
CSQRT: |jc r |, | x L | < 00 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 

C: 

ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 

TADD, TASS, TDIV, TDSS, TMLT, TMSS, TSUB, TSSS - Performs triple-precision arithmetic 

DESCRIPTION 

TADD, TASS - Triple-precision addition 
TDIV, TDSS - Triple-precision division 
TMLT, TMSS - Triple-precision multiplication 
TSUB, TSSS - Triple-precision subtraction 

Triple-precision arithmetic results are stored in three contiguous 64-bit computer words. In the first 
word, the high-order 16 bits contain the exponent, and the low-order 48 bits contain the first part of the 
value. The rest of the value is contained in the low-order 48 bits of the second and third words. The 
high-order 16 bits of the second and third words must be 0. If these routines are called from Fortran, 
the arguments must be passed in 3-word arrays. 

EXAMPLES 

Fortran: 

REAL C(3),D(3),RSLT(3) 
C(l) = 0 53210 4567012345670123B 
C(2) = 0 00000 0123456701234567B 
C(3) = 0 00000 7654321076454321B 
D(l) = 1 53266 7245435774406773B 
D(2) = 0 00000 0227373374570723B 
D(3) = 0 00000 0326757726541757B 
CALL TADD(C,D,RSLT) 

CAL: (Call by address) 

CALL TASS,(C1,C2,C3,D1,D2,D3) 

CAL: (Call by value) 



SI 


Cl.O 




S2 


C2,0 




S3 


C3,0 




S4 


Dl.O 




S5 


D2.0 




S6 


D3,0 




CALLV 


TASS% 




CI 


CON 


O'0532104567012345670123 


C2 


CON 


O'0000000123456701234567 


C3 


CON 


O , 0000007654321076454321 


Dl 


CON 


O" 1532667245435774406773 


D2 


CON 


O*0000000227373374570723 


D3 


CON 


O , 0000000326757726541757 



The results are returned in registers SI, S2, and S3. 
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NAME 

TAN, DTAN, tan - Computes tangent 

SYNOPSIS 

Fortran: 

r = TAN(rea/) 
d ~ DTAN(double) 



#include <math.h> 
double tan(x) 
double x; 



CAL register usage: 
Scalar TAN: 

TAN% (call by register) 
on entry (SI) = argument 
on exit (SI) = result 



Vector TAN: 

%TAN% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 



Scalar DTAN: 

DTAN% (call by register) 

on entry (SI) and (S2) = argument 

on exit (SI) and (S2) - result 



Vector DTAN: 

%DTAN% (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate y = tan(r). 

TAN and tan (callable only from C programs) return the real tangent of their real argument. 
DTAN returns the double-precision tangent of its double-precision argument. 

TAN is die generic function name. 

TAN and DTAN are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

\x \<2 U 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Cbde generation: External 
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ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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NAME 

TANH, DTANH, tanh - Computes hyperbolic tangent 
SYNOPSIS 



Fortran: 

r = TANH(reaZ) 
d = DTASH(double) 



C: 

#include <math.h> 
double tanh(x) 
double x; 



CAL register usage: 
Scalar TANH: 

TANH% (call by register) 
on entry (SI) = argument 
on exit (SI) = result 

Scalar DTANH: 

DTANH % (call by register) 

on entry (SI) and (S2) = arg words 1 and 2 

on exit (SI) and (S2) = result words 1 and 2 



Vector TANH: 

#>TANH% (call by register) 

on entry (VI) = argument vector 

on exit (VI) = result vector 

Vector DTANH: 

% DTANH % (call by register) 

on entry (VI) and (V2) = argument vector 

on exit (VI) and (V2) = result vector 



DESCRIPTION 

These functions evaluate y - tanh(x). 

TANH and tanh (callable only from C programs) return the real hyperbolic tangent of their real argu- 
ment. 

DTANH returns the double-precision hyperbolic tangent of its double-precision argument. 

TANH is the generic function name. 

TANH and DTANH are intrinsic for CFT and CFT77. 

ARGUMENT RANGE 

\x |<2 13 * ln2 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Fortran: 

ANSI Fortran 77 standard or Cray extension to standard: ANSI standard 
Level of vectorization: Full 
Code generation: External 
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ANSI C standard or Cray extension to standard: ANSI standard 
Level of vectorization: None 
Code generation: External 
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3* COS DATASET MANAGEMENT SUBPROGRAMS 



Dataset management subprograms provide the user with the means of managing COS permanent 
datasets; creating, staging, and releasing datasets; and changing dataset attributes. These routines are 
grouped into two subsections: 

• COS control statement type subprograms 

• COS dataset search type subprograms 

IMPLEMENTATION 

The dataset management routines are available only under COS. 

COS CONTROL STATEMENT TYPE SUBPROGRAMS 

A control-statement-type subprogram resembles Cray job control language (JCL) statements in name and 
purpose, A subprogram, however, can be called from within Fortran or CAL programs while a JCL 
statement cannot. See the COS Reference Manual, publication SR-0011, for a description of control 
statements, parameter and keywords, and JCL error codes. 

The following is an example of a Fortran call to a control-statement-type subprogram: 

EXAMPL= ' EXAMPL* L 
IIXVPR'L 

callassignowc;dn , l,exampl;u , l, , mr , l, , dc'l,idc) 

Variable irtc is an integer that contains a status code upon return. A status code of 0 indicates no errors. 

This type of subprogram requires call-by-address subroutine linkage with the following calling 
sequence: 

CALL SUBROUTINE NAME(statJteyl Jcey2,...,keyn) 
stat Returned status code 

key Keyword/value combinations in one of the following formats (must be entered in 

uppercase): 

'KEYWORD'WVALUE'L 
or 

'KEYWORDS 

When the keyword can accept multiple parameter values, the values must be passed as an array: one 
parameter per word, terminated by a zero word. For example, the COS control statement 
MODIFY(DN=DATASET,PAM=R:W) would be coded as follows: 

INTEGER PAM(3) 
DATA PAM/'R'L, 'W'L, 0/ 

CALL MODIFY(ISTAT, 'DN'L, 'DATASET'L, TAM'L, PAM) 
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Permanent Dataset Management routines access the COS Permanent Dataset Manager (PDM) and 
return the status of the operation in stat. The value is 0 if an error condition does not exist and nonzero 
if an error condition does exist The nonzero error codes correspond to the PMST codes defined in the 
COS Reference Manual. The following is a list of the PDM routines and their functions. 



Control Statement 
ACCESS 
ADJUST 
DELETE 

MODIFY 
PERMIT 
SAVE 



Function 

Associates a permanent dataset with the job 
Expands or contracts a permanent dataset 

Removes a saved dataset. The dataset remains available to the job until 
it is released or the job terminates. DELETE with PDN parameter 
requires special privilege SCRDSC (read Dataset Catalog). 

Changes the permanent dataset characteristics 

Specifies the user access mode to a permanent dataset 

Makes a dataset permanent and enters the dataset' s identification and 
location into the Dataset Catalog (DSC) 



Dataset staging routines stage datasets to or from a front-end processor or to the Cray input queue. 
The transfer aborts and an error code is returned if an error occurs. The error codes correspond to the 
PMST codes in the COS Reference Manual. The following is a list of dataset staging routines and their 
functions. 



Control Statement 
ACQUIRE 

DISPOSE 

FETCH 

SUBMIT 



Function 

Obtains a front-end resident dataset, stages it to the Cray mainframe, and 
makes it permanent and available to the job making the request 

Directs a dataset to the specified front-end processor or designates it to a 
scratch dataset 

Brings a front-end resident dataset to the Cray mainframe and makes the 
dataset available to the job 

Places a job dataset into the Cray input queue. When called as an integer 
function, the value of the function is the job sequence number of the sub- 
mitted job, if successful. 



Definition and control routines allow dataset attributes to be changed and datasets to be created and 
released. They return the status of the operation in stat. The value of the stat is 0 if no error condition 
exists and nonzero if an error condition exists* ASSIGN returns a three-digit code that corresponds to 
log file message codes that begin with SL. Thus, a return code of 020 from ASSIGN corresponds to the 
following log file message: 

SL020 - INVALID DATASET NAME OR UNIT NUMBER 

All of the SL messages and descriptions of their meanings can be found in the COS Message Manual, 
publication SR-0039. 
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The following is a list of definition and control routines. 
Control Statement Function 

ASSIGN Opens a dataset for reading and writing and assigns characteristics to it 

OPTION Changes the user-specified options, such as lines per page and dataset 

statistics, for a job 

RELEASE Closes a dataset, releases I/O buffer space, and renders it unavailable to 

the job 

COS DATASET SEARCH TYPE SUBPROGRAMS 

Dataset search subprograms add information to or return information about a dataset. 

The following table contains the purpose, name, and heading of each dataset search type routine. 



COS Dataset Search Ty] 


:>e Subprograms 


Purpose 


Name 


Heading 


Add a name to the Logical File 
Table (LFT) 


ADDLFT 


ADDLFT 


Search for a Dataset Parameter 
Table (DSP) address 


GETDSP 


GETDSP 


Determine if a dataset has been 
accessed or created 


IFDNT 


IFDNT 


Allow a program to access datasets 
in the System Directory 


SDACCESS 


SDACCESS 
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NAME 

ADDLFT - Adds a name to the Logical File Table (LFT) 

SYNOPSIS 

CALL ADDLFT(dn,<fcp) 

DESCRIPTION 

dn Name to add to the LFT 

dsp Dataset Parameter Table (DSP) address for the name specified by dn 

IMPLEMENTATION 

This routine is available only to the users of the COS operating system. 
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NAME 

CALLCSP - Executes a COS control statement 

SYNOPSIS 

CALL CALLCSP(j/ri«$) 

DESCRIPTION 

siring A valid COS JCL statement, either packed into an integer array and terminated by a null 
byte or specified as a literal string. 

The control statement specified in the string is executed as if it had been found next in the job stream. 
For example, the following call invokes the NOTE utility, which writes HIGH, THEIR! to the $OUT 
dataset: 

CALL CALLCSP(*NOTE,TEXT="HIGH, THEIR!".') 
Control does not return from the CALLCSP routine. 

NOTE 

In general, use CALLCSP instead of LGO. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

GETDSP - Searches for a Dataset Parameter Table (DSP) address 

SYNOPSIS 

CALL GETHSP(umt4spjidsp4n) 

DESCRIPTION 

unit Dataset name or unit number 

dsp DSP address 

ndsp Negative DSP offset relative to the base address of DSPs, or DSP address if die DSP is below 
JCHLM. 

dn Dataset name (ASCII, left-justified, blank-filled) 

GETDSP searches for a DSP address. If none is found, a DSP is created. 

IMPLEMENTATION 

This routine is available only to the users of the COS operating system. 
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NAME 

IFDNT - Determines if a dataset has been accessed or created 

SYNOPSIS 

stat=I¥DNT(dn) 

DESCRIPTION 

stat -1 (TRUE) if dataset was accessed or opened; otherwise 0 (FALSE). 

dn Dataset name (ASCII, left-justified, zero-filled) 

NOTE 

IFDNT and stat must be declared LOGICAL in the calling program. 
EXAMPLE 

IF (.NOT. IFDNTCMYFILE'L)) CALL ACCESSflSTAT/DN'L/MYFILE'L) 

If you access MYFILE twice in a program, the system aborts the job. IFDNT allows you to test for its 
having been previously accessed. 

IMPLEMENTATION 

This routine is available only to the users of the COS operating system. 

The function of IFDNT can be achieved through the Fortran INQUIRE routine, which is available under 
both COS and UNICOS. 
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NAME 

SDACCESS - Allows a program to access datasets in the System Directory 

SYNOPSIS 

CALL SDACCESS(istat,dn) 
DESCRIPTION 

istat An integer variable to receive the completion status (0 or 1). 

0 The dataset is a system dataset and has been accessed. 

1 The dataset is not a system dataset and has not been accessed. 

dn Name of the system dataset to be accessed 

This function has no corresponding control statement. Datasets accessed in this manner are automati- 
cally released at the end of the job step. 

EXAMPLE 



PROGRAM SDTEST 
CHARACTER*7 NAME 
INTEGER X 
READ*, NAME 
X=IFDNT(NAME) 
IF(X.EQ.0)THEN 

PRINT* , ***DATASET '.NAME, 'WAS NOT LOCAL***' 

CALL SDACCESS(STAT.NAME) 

IF (STAT.NE.0) THEN 

PRINT*. '***DATASET '.NAME.' NOT AVAILABLE' 
CALL ABORT 

ELSE 

PRINT*. '***DATASET '.NAME.' ACCESSED BY SDTEST' 
ENDIF 
ELSE 

PRINT*, 'DATASET '.NAME,' ALREADY LOCAL' 
ENDIF 
END 



IMPLEMENTATION 

This routine is available only to the users of the COS operating system. 
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4. LINEAR ALGEBRA SUBPROGRAMS 



The linear algebra subprograms are written to run optimally on Cray computer systems. These subpro- 
grams use call-by-address convention when called by a Fortran, C, or CAL program. 

The linear algebra subprograms include the following: 

• Basic linear algebra subprograms 

• Linear recurrence routines 

• Matrix inverse and multiplication routines 

• Filter routines 

• Gather-scatter routines 

• UNPACK and EISPACK routines 



Basic Linear Algebra Subprograms 

The Cray computer user has access to the Basic Linear Algebra Subprograms (BLAS), the level 2 BLAS 
(BLAS 2), and the level 3 BLAS (BLAS 3). The level 1 package is described first, and is followed by 
descriptions of the level 2 and level 3 packages. 



BLAS 

The level 1 BLAS is a package of CAL-coded routines and their extensions, BLAS routines are 
used for basic vector operations. The package includes only the single-precision and complex 
versions. The following operations are available: 

• A constant times a vector plus another vector 

• Dot products 

• Euclidean norm 

• Givens transformations 

• Sum of absolute values 

• Vector copy and swap 

• Vector scaling 
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Each BIAS routine has a real version and a complex version. There are several frequently used 
variables that must be declared in your program. The following table lists common variables and 
their Fortran type declaration and dimensions, in generalized terms. 



Linear Algebra Variables 


Variable 


Description 


Fortran Type and Dimension 


SX 


Primary real array or vector 


REAL SX(mx) 


SY 


Secondary real array or vector 


REAL SY(my) 


SA 


Real scalar 


REAL SA 


cx 


Primary complex array or vector 


COMPLEX CX(mx) 


CY 


Secondary complex array or vector 


COMPLEX CY(my) 


CA 


Complex scalar 


COMPLEX CA 


1NCX 


Increment between elements 
in SX or CX 


INTEGER INCX 


INCY 


Increment between elements 
in SY or CY 


INTEGER INCY 


N 


Number of elements in vector to compute 


INTEGER N 



The minimum dimensions of the preceding arrays are as follows: >nx=l+(N-l)*|INCX| and 
my=l+(N-l)*(INCY| ( respectively; where N is the length of each vector operand. In all routines, 
if N <0, inputs and outputs return unchanged. 

The Fortran type declaration for complex functions is especially important; declare them to avoid 
type conversion to zero imaginary parts. Fortran type declarations for function names follow: 

Type Function Name 

REAL SASUM, SCASUM, SDOT, SNRM2, SCNRM2 

COMPLEX CDOTC, CDOTU 

Negative incrementation - For routines managing noncontiguous elements in a one-dimensional 
array, the parameters incx and incy specify increments. An increment value of 1 or -1 indicates 
contiguous elements. 

Given an /i-element array A consisting of A(l), A(2), A(3),.*.,A(n), for positive increments (incx > 
0): 

• The managed array elements are as follows: 

A(l), A(l+/ncx), A(l+2*incx), A(l+3* incx\.»> A(l+(p4)*uicx), 
where p is the number of array elements to be processed. 

♦ For n MODULO incx > 0, p l+-r^-. Otherwise, p < t^— . 

tncx incx 
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Given the previous array and a negative increment (incx < 0): 

• The managed array elements are as follows: 
A(l+(p-l)*ABS(/nct)), 

A(l+(p-2)*ABS(i/»cx)), A(l+(p-3)*ABS(incx)), 
A(l+(p-4)*ABS(incx)),^.,A(l+(p-p)*ABS(incc)), 

where p is the number of array elements to be processed. 

• For n MODULO incx >0 r p< 1+ , — r . Otherwise, p < , — - . 

EXAMPLE - The real function ISAMAX returns the relative index of I such that 
ABS(A(T)) = MAX ABS(A(1+(J-1)*INCX)) for 1=1,2,3,...^. 

The call from Fortran is as follows: 

RELINDEX = lSAMAX(p#rrayjncx) 

Assume A(l)=2.0, A(2)=4.0, A(3)=6.0,...,A(20)=40.0 (the number of elements »=20). 

With a positive increment (incx=3), the number of elements processed p=7 
(since 20 MODULO 3 > 0, p = 1+n/incx = 1+20/3 = 1+6 = 7). 

Therefore, the function is evaluated as follows: 

ISAMAX(7,A,3)= 

rel. index of MAX (2.0,8.0,14.0,20.0,26.0,32.038.0) 
= relative index of 38.0 
= 7 

With a negative increment incx=-3, the number of elements processed p=7 
(since 20 MODULO ABS(-3) > 0, p = l+n/ABS(mcx) - 1+20/3 = 1+6 = 7. 

Therefore, the function is evaluated as follows: 

ISAMAX(7,A,-3)= 

rel. index of MAX (38.0,32.0,26.0,20.0,14.0,8.0,2.0) 
= relative index of 38.0 
= 1 
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The following table contains the purpose, name, and manual entry of each level 1 BLAS routine. 

The ''manual entry" is the name of the manual page containing documentation for the routine(s) 
listed. 



Level 1 BLAS 


Purpose 


Name 


Manual Entry 


Sum the absolute values of a real or 


SASUM 


SASUM 


complex vector 


SCASUM 




Add a scalar muitiDle of a real or 


SAXPY 


SAXPY 


complex vector to another vector 


CAXPY 




v>upy a reai or complex vector mio 




atwi 


another vector 


CCOPY 




Appiy a complex uivens piane roiaoon 




tKU 1 


v^urnpuie d complex viivons piane roiauon uidinx 




LKUlu 


Compute a dot product of two real 


sdot 


DOT 


or complex vectors 


CDOTC 
CDOTU 




Scale a real or complex vector 


OP/1 A ¥ 

CSSCAL 


SCAL 


v^oiTipuic me piuauci oi a column vector 


SMYPV 


CMYPV 


and a matrix and add to another column 






vector 






ComDute the oroduct of a row vector and a 


SXMPY 


SXMPY 


matrix and add to another row vector 






Comnute the Euclidean norm or 


SNRM2 


SNRM2 


/o norm of a real or comnlex 


SCNRM2 




vector 






Compute a sparse dot product of two 
real vectors or add a scalar multiple 


SPDOT 
SPAXPY 


SPDOT 


of a vector to a sparse vector 






Apply an orthogonal plane rotation 


SROT 


SROT 


Construct a Givens plane rotation 


SROTG 


SROTG 


Apply a modified Givens plane 


SROTM 


SROTM 


rotation 






Construct a modified Givens plane 


SROTMG 


SROTMG 


rotation 






Sum the elements of a real or 


SSUM 


SSUM 


complex vector 


CSUM 




Swap two real or two complex arrays 


SSWAP 
CSWAP 


SSWAP 
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BLAS 2 

The Basic Linear Algebra Subprograms, level 2 (BLAS 2), consist of CAL routines for unpacked 
data of type real and complex. They handle matrix-vector operations. The following table 
describes these routines. The "manual entry" is the name of the manual page containing docu- 
mentation for the routine(s) listed. NOTE: Routines for type complex data (beginning with "C") 
are available only to COS users. 



Level 2 BLAS 


Purpose 


Name 


Manual Entry 


Mill fin! v si tpjiI vat tor hv a rpal pfttipjral 

XVXlXltXLJXJT Cl 1- vflU T W» LKJl Uj CI Ivftl ££VllVi£(X 

band matrix 


SGBMV 


SGBMV 


Multinlv a comnlex vector bv a comnlex general 
band matrix 


CGBMV 


CGBMV 


Multiply a real vector by a real general matrix 


SGEMV 


SGEMV 


Multinlv a comnlex vector bv a comnlex general 

XV Jl WAUL/* J ** ■ T V^-r tAJl U J V* W»vA tVIlvltU 

matrix 


CGEMV 


CGEMV 


PprffM*m rftnlr 1 litvifltp of n rasi! uptipjtaI 

X Ksl L \Jl VI L A tUlK X U ^/VWll.V' V/X A 1 veil gV/HV/A OX 

matrix 


SGER 

kj VJ x^xv 


SGER 

LJ VJT UiJLX 


Ppt*fnrtTi rrwiincrsitp/i rjinlr 1 nnHiitp of" a pomolpY 

general matrix 


CGFRC 


CGERC 

V- VJ XL<IX 


T^prform iitipotiiiip^ifprf futile 1 nfifintp of a rnrnnl^Y 

general matrix 


CGERIJ 


CGERIJ 


IVlLliLipiy « ICal VCvlvJI uy it iCal djrlllillClilC' 

band matrix 






ivimix^/ljr <| lAJlllJ/lGA VCV<IXJI Ujf A VAJlll|'KsA xxCxIlliLxall 

band matrix 


CHRMV 


CHRMV 


jviuiupiy a rc<±i vecujr oy a real ayniiiicuiv iiiduiA 


CCVMV 
i3o r ivi v 




Multiply a complex vector by a complex Hermitian 
matrix 


CHEMV 


CHEMV 


Perform symmetric rank 1 update of a real 
symmetric mainx 


SSYR 


SSYR 


Hermitian matrix 


V^X AXlrfJX 


V^X A XZ^CV 


Pprfoirn ovtyi ttiPtrip rfltitc 0 iirwiiitp of a rpfll 

symmetric matrix 

^ 


tJtJ M. XX At 




Perform Hermitian rank 2 update of a complex 
Hermitian matrix 


CHER2 


CHER2 


Multiply a real vector by a real triangular 
hand matrix 


STBMV 


STBMV 


Multiply a complex vector by a complex triangular 
band matrix 


CTBMV 


CTBMV 


Solve a real triangular banded system 
of equations 


STBSV 


STBSV 


Solve a complex triangular banded system 
of equations 


CTBSV 


CTBSV 


Multiply a real vector by a real triangular matrix 


STRMV 


STRMV 


Multiply a complex vector by a complex triangular 
matrix 


CTRMV 


CTRMV 


Solve a real triangular system of equations 


STRSV 


STRSV 


Solve a complex triangular system of equations 


CTRSV 


CTRSV 
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Level 2 BIAS routines for packed data are also available, but they are written in unoptimized 
Fortran and CRI does not recommend their use. They will be optimized in a future release. 

BLAS3 

The Basic Linear Algebra Subprograms, level 3 (BLAS 3), consist of CAL routines for unpacked 
data of type real and complex. They handle matrix-matrix operations. The following table 
describes these routines. NOTE: These routines are available only to COS users. 

The "manual entry" is the name of the manual page containing documentation for the routine(s) 
listed. 

The last two routines in this table, SGEMMS and CGEMMS, are Cray extensions to the standard 
set of BLAS 3 routines. 



Level 3 BLAS (COS only) 


Purpose 


Name 


Manual Entry 


Multiply a real general matrix by 
a real general matrix 


SGEMM 


SGEMM 


Multiply a complex general matrix by 
a complex general matrix 


CGEMM 


CGEMM 


Multiply a real general matrix by 
a real symmetric matrix 


SSYMM 


SSYMM 


Multiply a complex general matrix by 
a complex symmetric matrix 


CSYMM 


CSYMM 


Multiply a complex general matrix by a 
complex Hermitian matrix 


CHEMM 


CHEMM 


Perform symmetric rank k update of a 
real symmetric matrix 


SSYRK 


SSYRK 


Perform symmetric rank k update of a 
complex symmetric matrix 


CSYRK 


CSYRK 


Perform Hermitian rank k update of a 
complex Hermitian matrix 


CHERK 


CHERK 


Perform symmetric rank 2k update of a 
real symmetric matrix 


SSYR2K 


SSYR2K 


Perform symmetric rank 2k update of a 
complex symmetric matrix 


CSYR2K 


CSYR2K 


Perform Hermitian rank 2k update of a 
complex Hermitian matrix 


GHER2K 


CHER2K 


Multiply a real general matrix by a 
real triangular matrix 


STRMM 


STRMM 


Multiply a complex general matrix by a 
complex triangular matrix 


CTRMM 


CTRMM 


Solve a real triangular system of equations 
with multiple right-hand sides 


STRSM 


STRSM 


Solve a complex triangular system of equations 
with multiple right-hand sides 


CTRSM 


CTRSM 


Multiply a real general matrix by a 
real general matrix using a variation 
of Strassen's algorithm 


SGEMMS 


SGEMMS 


Multiply a complex general matrix by a 
complex general matrix using a variation 
of Strassen's algorithm 


CGEMMS 


CGEMMS 
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Linear Recurrence Routines 

Linear recurrence routines solve first-order and some second-order linear recurrences, A linear 
recurrence uses the result of a previous pass through the loop as an operand for subsequent passes 
through the loop* thereby preventing vectorization. Therefore, these routines can be used to optimize 
Fortran loops containing linear recurrences. 

The following table contains the purpose, name, and manual entry of each linear recurrence routine. 
The "manual entry" is the name of the manual page containing documentation for the routine(s) listed. 



Linear Recurrence Subroutines 


Purpose 


Name 


Manual Entry 


Solve first-order linear recurrences, 
overwriting input vector 


FOLR 
FOLRP 


FOLR 


Solve first-order linear recurrences 
and write the solutions to a new vector 


FOLR2 
FOLR2P 


FOLR2 


Solve special first-order linear recurrences 


FOLRC 


FOLRC 


Solve for the last term of a first-order 
linear recurrence using Homer's method 


FOLRN 


FOLRN 


Solve for the last term of a 
first-order linear recurrence 


FOLRNP 


FOLRNP 


Solve second-order linear recurrences 


SOLR 

SOLRN 

SOLR3 


SOLR 


Compute partial products 


RECPP 


RECPP 


Compute partial sums 


RECPS 


RECPS 



Matrix Inverse and Multiplication Routines 

The matrix inverse subroutine, MINV, solves systems of linear equations by inverting a square matrix, 
using Gauss-Jordan elimination. MXM and MXMA are two optimized matrix multiplication routines. 
MXV and MXVA are similar to MXM and MXMA; however, MXV and MXVA handle the special case of 
matrix times vector multiplication. 

The following table contains a summary of the matrix inverse and multiplication routines. 

The "manual entry" is the name of the manual page containing documentation for the routine(s) listed. 



Matrix Inverse and Multiplication Routines 



Purpose 


Name 


Manual Entry 


Solve systems of linear equations 
by inverting a square matrix 


MINV 


MINV 


Multiply a matrix by another matrix 
(unit increments) 


MXM 


MXM 


Multiply a matrix by another matrix 
(arbitrary increments) 


MXMA 


MXMA 


Multiply a matrix and a vector 
(unit increments) 


MXV 


MXV 


Multiply a matrix and a vector 
(arbitrary increments) 


MXVA 


MXVA 
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Filter Routines 

The filter routines are used for filter analysis and design. They also solve more general problems. For 
detailed descriptions, algorithms, performance statistics, and examples, see Linear Digital Filters for 
CFT Usage, CRI publication SN-0210, 

The following table contains a summary of the filter routines. 

The "manual entry" is the name of the manual page containing documentation for the routine(s) listed. 



Filter Routines 


Purpose 


Name 


Manual Entry 


Compute a correlation of two vectors 


FTLTERG 


FILTERG 


Compute a correlation of two vectors 
(assuming the filter coefficient 
vector is symmetric) 


FILTERS 


FILTERS 


Solve the Weiner-Levinson linear 
equations 


OPFILT 


OPFILT 



Gather-Scatter Routines 

The GATHER and SCATTER routines gather a vector from a source vector or scatter a vector into 
another vector, given a vector of indices specifying which elements of the source or target vector are to 
be accessed or changed. 



UNPACK and EISPACK Routines 

UNPACK routines solve systems of linear equations and compute the QR, Cholesky, and singular value 
decompositions. EISPACK routines solve eigenvalue problems; they also compute and use singular 
value decompositions, 

Single-precision Real and Complex LINPACK Routines 

UNPACK is a package of Fortran routines that solve systems of linear equations and compute the 
QR, Cholesky, and singular value decompositions. The original Fortran programs are documented 
in the UNPACK User's Guide by J. J. Dongarra, C. B, Moler, J. R. Bunch, and G. W. Stewart, 
published by the Society for Industrial and Applied Mathematics (SIAM), Philadelphia, 1979, 
Library of Congress catalog card number 78-78206 (available through Cray Research as publica- 
tion Sl-0113). 

Each single-precision version of the LINPACK routines has the same name, algorithm, and calling 
sequence as the original version. Optimization of each routine includes the following; 

• Replacement of calls to the BLAS routines SSCAL, SCOPY, SSWAP, SAXPY, and SROT 
with in-line Fortran code vectorized by Cray Fortran compilers 

• Removal of Fortran IF statements where the result of either branch is the same 

• Replacement of SDOT to solve triangular systems of linear equations in SGESL, SPOFA, 
SPOSL, STRSL, and SCHDD with more vectorizable code 

These optimizations affect only the execution order of floating-point operations in modified DO 
loops. See the LINPACK User's Guide for further descriptions. The complex routines have been 
added without extensive optimization. 
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Single-precision EISPACK Routines 

EISPACK is a package of Fortran routines for solving the eigenvalue problem and for computing 
and using the singular value decomposition. 

The original Fortran versions are documented in the Matrix Eigensystem Routines - EISPACK 
Guide, second edition, by T. B, Smith, J. M. Boyle, J. J. Dongaira, B. S. Garbow, Y, Ikebe, V. C. 
Klema, and C B. Moler, published by Springer-Verlag, New York, 1976, Library of Congress 
catalog card number 76-2662 (available through Cray Research as publication S2-01 13); and in the 
Matrix Eigensystem Routines - EISPACK Guide Extension by B. S. Garbow, J. M. Boyle, J. J. 
Dongarra, and C. B. Moler, published by Springer- Verlag, New York, 1977, Library of Congress 
catalog card number 77-2802 (available through Cray Research as publication S3-0113). 

Each libsci version of the EISPACK routines has the same name, algorithm, and calling sequence 
as the original version. Optimization of each routine includes the following: 

• Use of the BLAS routines SDOT, SASUM, SNRM2, ISAM AX, and ISMIN when applica- 
ble 

• Removal of Fortran IF statements where the result of either branch is the same 

• Unrolling complicated Fortran DO loops to improve vectorization 

• Use of the Fortran compiler directive CDIR$ IVDEP when no dependencies preventing 
vectorization exist 

These modifications increase vectorization and, therefore, reduce execution time. Only the order 
of computations within a loop is changed; the modified version produces the same answers as the 
original versions unless the problem is sensitive to small changes in the data. 
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NAME 

CGBMV - Multiplies a complex vector by a complex general band matrix 
SYNOPSIS 

CALL CGBMV (trans m»n t kl,ku y alpha,a t lda 1 x,incx 3 beta i y t incy) 
DESCRIPTION 

CGBMV performs one of the following matrix-vector operations: 

3? := alpha*a*x+beta*y 9 
or y alpha*a'*x+beta*y, 
or y := a/p/m*conjg( r a J ')*x+beta*y 

Arguments alpha and beta are scalars, x and y are vectors, a is an m-by-n band matrix, kl is a number 
of subdiagonals, ku is a number of superdiagonals, and a 1 is the transpose of a. 

trans Type character* 1, 

On entry, trans specifies the operation to be performed: 

If trans = 'N' or 'n\ y := alpha*a*x+beta*y. 
If trans = T* or *t\ 3? := alpha*a'*x+beta*y. 
If &ym.s = 'C or *c\ y := a/pAa*conjg((3')*jc+&£/a*y. 

On exit, trans is unchanged. 

w Type integer. 

On entry, m specifies the number of rows in matrix a. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

kl Type integer. 

On entry, kl specifies the number of subdiagonals of matrix a. 
Argument kl must satisfy O.LEjW. 
On exit, kl is unchanged. 

ku Type integer. 

On entry, ku specifies the number of superdiagonals of matrix a. 
Argument ku must satisfy 0.LE.&W. 
On exit, ku is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 
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a Type complex. 

Array of dimension (Ida y n). 

Before entry, the leading (£/+fcK+l)-by-n part of array a must contain the matrix of coefficients, 
supplied column by column, with the leading diagonal of the matrix in row (jfcu+1) of the array, 
the first superdiagonal starting at position 2 in row ku f the first subdiagonal starting at position 
1 in row (jfcu+2), and so on. Elements in array a that do not correspond to elements in the band 
matrix (such as the top left ku-by-ku triangle) are not referenced. 

The following program segment will transfer a band matrix from conventional full matrix 
storage to band storage: 

DO 20 , J = 1, N 
K = KU + 1 - J 

DO 10, 1- MAX(1, J - KU), MIN(M, J + KL) 
A(K + I, J) = MATRIX(I, J) 
10 CONTINUE 
20 CONTINUE 



On exit, a is unchanged. 
Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
Argument Ida must be at least (kl+ku+1). 
On exit, Ida is unchanged. 

x Type complex. 

Array of dimension at least: 

l+(n-l)*\incx\ when trans = *N' or *n\ 

l+(m- 1 )* | incx \ otherwise. 

Before entry, the incremented array x must contain vector x. 
On exit, x is unchanged. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

beta Type complex. 

On entry, beta specifies the scalar beta. 

When beta is supplied as 0, y need not be set on input. 

On exit, beta is unchanged. 

y Type complex. 

Array of dimension at least: 

l+(m-\)*\incy\ when trans = *N' or *n\ 

l+(/i-l)*|i/wry| otherwise. 

Before entry, the incremented array y must contain vector y. 
On exit, y is overwritten by updated vector y. 

incy Type integer. 

On entry, incy specifies the increment for the elements of y. 
Argument incy must not be 0. 
On exit, incy is unchanged. 
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IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CGBMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

CGEMM - Multiplies a complex general matrix by a complex general matrix 
SYNOPSIS 

CALL CGEMM(trmsa t transbM f nJc,alpha,aJda,b,ldb,beta t c,ldc) 

DESCRIPTION 

CGEMM performs one of the matrix-matrix operations: 

c := alpha*op{a)*op(b)+beta*c 

where opto) is one of the following: 

op(x) = x y 

or op(x) =x\ 

or op(x) « conjg(x*) 

Arguments alpha and beta are sealars, a, b, and c are matrices, op(a) is an m-hy-k matrix, op(Z>) is a 
Jfc-by-n matrix, and c is an ra-by-n matrix. 

transa Type character* 1. 

On entry, transa specifies the form of ap(a) to be used in the matrix multiplication as follows: 

If transa = *N' or *n\ op(a) = a. 
If transa = *T or Y, op(a) = a 1 . 
If fra/wa = 'C or *c\ op(a) = conjg(a'). 

On exit, transa is unchanged. 

transb Type character* 1. 

On entry, transb specifies the form of op(6) to be used in the matrix multiplication as follows: 

If transb = *N' or *n\ op(&) = &. 
If transb = T* or Y, op(6) = b\ 
If transb = 'C* or V, op(6) = conjg(f>'). 

On exit, transb is unchanged. 

m Type integer. 

On entry, m specifies the number of rows in matrix op(a) and in matrix c. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in matrix op(b) and in matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry, k specifies the number of columns of matrix op(a) and the number of rows of matrix 
op(!>). 

Argument k must be at least 0. 
On exit, k is unchanged. 
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alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

a Type complex. 

Array of dimension (Ida, ka)> 

Argument ka is k when transa = *N* or *n\ and is m otherwise. 

Before entry with transa = *N* or V, the leading m-hy-k part of array a must contain matrix a. 
Otherwise, the leading k-by-m part of array a must contain matrix a. 
On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
When transa - *N* or *n\ Ida must be at least max(l, m). 
Otherwise, Ida must be at least max(l, k). 
On exit, Ida is unchanged. 

b Type complex. 

Array of dimension (ldb y kb). 

Argument kb is n when /ra/wfr « *N' or *n\ and is k otherwise. 

Before entry with transb = 'N' or V, the leading k-by-n part of array b must contain matrix 6. 
Otherwise, the leading n-by-k part of array b must contain matrix b. 
On exit, 6 is unchanged. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (sub)program. 
When transb = *N' or *n\ Idb must be at least max(l, k). 
Otherwise, Idb must be at least max(l, ri). 
On exit, Idb is unchanged. 

beta Type complex. 

On entry, beta specifies the scalar beta. 

When beta is supplied as 0, c need not be set on input. 

On exit, beta is unchanged. 

c Type complex. 

Array of dimension (Idc, n). 

Before entry, the leading w-by-n part of array c must contain matrix c, except when beta is 0, 
in which case c need not be set on entry. 

On exit, array c is overwritten by the m-by-n matrix (alpha*op(a)*op(b)+beta*c). 
Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (sub)program. 
Argument Idc must be at least max(l, m). 
On exit, Idc is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system, 

NOTE 

CGEMM is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 

SEE ALSO 

CGEMMS(3COS) 
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NAME 

CGEMMS - Multiplies a complex general matrix by a complex general matrix using Strassen's algo- 
rithm 

SYNOPSIS 

CALL CGEMMS(transa t transb,m,nJc t alpha t aJda,bMb,beta,cM^ 
DESCRIPTION 

Routine CGEMMS is functionally equivalent to CGEMM, except for the additional parameter, work. 
The primary difference is that CGEMMS is implemented using Winograd's variation of Strassen's algo- 
rithm for matrix multiplication, which is significantly faster for large matrices. 

Strassen's algorithm for matrix multiplication is a complex, recursive algorithm that performs the multi- 
plication in a manner completely different from the usual inner product method. While the inner pro- 
duct method reqires a number of operations on the order of n 3 (where n is the dimension of the 
matrices), Strassen's algorithm requires, in theory, a number of operations on the order of n 2 % . The tra- 
deoff is that Strassen's algorithm requires a work array in memory of size 234 */? 2 . Specifically, 
CGEMMS requires a complex array, work, supplied by the calling program, of size at least 

2.34*max(m, £)*max(£, n) 

(or equivalently, a real array of twice this dimension). 

The work array is overwritten, and no diagnostic is given if the supplied array is too small. 

Numerical results from CGEMMS may differ slightly from those of CGEMM, owing to a very different 
order of operations carried out by Strassen's algorithm. 

CGEMMS can be called for any values of the parameters that are legal for CGEMM. A performance 
improvement over CGEMM would not be expected, however, unless the minimum of the array dimen- 
sions is at least 128. For small dimensions, performance is approximately the same as CGEMM. 



CGEMMS performs one of the matrix-matrix operations: 
c := alpha*op(a)*op(p)+beta*c 
where op(x) is one of the following: 

op(x) = x, 
or op(x)=x\ 
or op(x) « conjgOO 

Arguments alpha and beta are scalars, a, b> and c are matrices, op(a) is an m-by-k matrix, op(&) is 
a k-by-n matrix, and c is an m-by-n matrix. 
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transa Type character* 1. 

On entry, transa specifies the form of op(a) to be used in the matrix multiplication as follows: 

If transa = *N* or *n\ op(a) = a. 
If transa = *T* or Y, op(a) = a\ 
If transa = *C or V, op(a) = conjg(a'). 

On exit, transa is unchanged. 

transb Type character* 1 . 

On entry, transb specifies the form of op(6) to be used in the matrix multiplication as follows: 

If transb = f N f or V, op(6) = b. 
If transb = T or *t\ op(6) = 6*. 
If transb ~ 9 C* or *c\ op(b) ~ conjg(fo')- 

On exit, transb is unchanged. 

m Type integer. 

On entry, m specifies the number of rows in matrix op(a) and in matrix c. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in matrix op(&) and in matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry, k specifies the number of columns of matrix op(<z) and the number of rows of matrix 
0P(». 

Argument k must be at least 0. 
On exit, k is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

a Type complex. 

Array of dimension (Ida, ka). 

Argument ka is k when transa ~ *N' or V, and is m otherwise. 

Before entry with transa = *N* or V, the leading m-by-k part of array a must contain matrix a. 
Otherwise, the leading jfc-by-m part of array a must contain matrix a. 
On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 
When transa = *N* or V, Ida must be at least max(l, m). 
Otherwise, Ida must be at least max(l, k). 
On exit, Ida is unchanged. 

b Type complex. 

Array of dimension (ldb f kb). 

Argument kb is n when transb = *N' or *n\ and is k otherwise. 

Before entry with transb = 'N' or *n\ the leading k-by-n part of array b must contain matrix b. 
Otherwise, the leading n-by-k part of array b must contain matrix b. 
On exit, b is unchanged. 
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Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (subprogram. 
When transb = *N* or V, Idb must be at least max(l, it). 
Otherwise, Idb must be at least max(l, n). 
On exit, Idb is unchanged. 

beta Type complex. 

On entry, beta specifies the scalar beta. 

When beta is supplied as 0, c need not be set on input. 

On exit, beta is unchanged. 

c Type complex. 

Array of dimension (Wc, /*). 

Before entry, the leading m by n part of array c must contain matrix c, except when beta is 0, 
in which case c need not be set on entry. 

On exit, array c is overwritten by the m by n matrix (alpha*op(a)*op(b)+beta*c). 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (sub)program. 
Argument Idc must be at least max(l, m). 
On exit, Idc is unchanged. 

work Type complex. 

Array of dimension 234*maxO?i, Jb)*max(£, /i). 
Used for scratch storage. 
On exit, work is overwritten. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTES 

CGEMMS is a CRI extension to the standard level 3 Basic Linear Algebra Subprograms (BLAS 3). 

SEE ALSO 

CGEMM(3COS> 
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NAME 

CGEMV - Multiplies a complex vector by a complex general matrix 
SYNOPSIS 

CALL CGEMV(trans,m,n,alpha,aJda t x,incx t beta f y,incy) 
DESCRIPTION 

CGEMV performs one of the following matrix-vector operations: 

y :- alpha*a*x+beta*y 9 
or y := alpha* a' *x+beta*y, 
or y := alpha*conjg(a')*x+beta*y 

Arguments alpha and beta are scalars, x and y are vectors, a is an m-by-n matrix, and a' is the tran 
spose of a, 

trans Type character* 1. 

On entry, trans specifies the operation to be performed: 

If trans = f N* or V, y := alpha* a*x+beta*y. 
If trans = T or Y, y := alpha*a'*x+beta*y. 
If flms = 'C or *c\ y := alpha*conjg(a')*x+beta*y. 

On exit, /ra/w is unchanged. 

m Type integer. 

On entry, m specifies the number of rows in matrix a. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

a Type complex. 

Array of dimension (Ida, n). 

Before entry, the leading m-by-n part of array a must contain the matrix of coefficients. 
On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program, 
Argument Ida must be at least max(l, m) 
On exit, Ida is unchanged. 
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x Type complex. 

Anay of dimension at least: 

\+(n-Y)*\incx\ when trans = 'N* or V, 

l+(w-l)*ji>icx| otherwise. 

Before entry, the incremented array jc must contain vector x. 
On exit, x is unchanged. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

beta Type complex. 

On entry, beta specifies the scalar beta. 

When beta is supplied as 0, y need not be set on input. 

On exit, beta is unchanged. 

y Type complex. 

Array of dimension at least: 

l+(m-l)*\incy\ when trans = *N* or *n\ 

l+(/i-l)*|//ury| otherwise. 

Before entry, with beta non-zero, the incremented array y must contain vector y. 
On exit, y is overwritten by updated vector y. 

incy Type integer. 

On entry, incy specifies the increment for the elements of y. 
Argument incy must not be 0. 
On exit, incy is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CGEMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

CGERC - Performs conjugated rank 1 update of a complex general matrix 
SYNOPSIS 

CALL CGERC{m t n,alphax,incx t y t incy>a,lda) 

DESCRIPTION 

CGERC performs the rank 1 operation: 

a := alpha*x*conjg(f )+a 

Argument alpha is scalar, x is an m element vector, y is an n element vector, and a is an m-by-n 
matrix. 

m Type integer. 

On entry, m specifies the number of rows in matrix a. 
Argument m must be at least 0. 
On exit, m is unchanged, 

n Type integer. 

On entry, n specifies the number of columns in matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

x Type complex. 

Array of dimension at least: 

1«K»i-1)*|micx|. 

Before entry, the incremented array x must contain the m element vector x. 
On exit, x is unchanged. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

y Type complex. 

Array of dimension at least: 

l+(»-l)*|iiicy|. 

Before entry, the incremented array y must contain the n element vector y. 
On exit, y is unchanged. 

incy Type integer. 

On entry, incy specifies the increment for the elements of y. 
Argument incy must not be 0. 
On exit, incy is unchanged. 
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a Type complex. 

Array of dimension {Ida, n). 

Before entry, the leading m-by-n part of array a must contain the matrix of coefficients. 
On exit, a is overwritten by the updated matrix. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
Argument Ida must be at least max(l, m). 
On exit, Ida is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CGERC is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 



SR-0113 



4-21 



D 



CGERU (3COS) 



CGERU(3C0S) 



NAME 

CGERU - Performs unconjugated rank 1 update of a complex general matrix 
SYNOPSIS 

CALL CGER\J(m,n,alphajMcx,y,incy t a f lda) 

DESCRIPTION 

CGERU performs the rank 1 operation; 

a alpha*x*f +a 

Argument alpha is scalar, x is an m element vector, y is an n element vector, and a is an m-by-n 
matrix. 

m Type integer. 

On entry, m specifies the number of rows in matrix a. 
Argument m must be at least 0. 
On exit, m is unchanged 

n Type integer. 

On entry, n specifies the number of columns in matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

x Type complex. 

Array of dimension at least: 

l+(m-l)*|/rtc4 

Before entry, the incremented array x must contain the m element vector x* 
On exit, x is unchanged. 

incx Type integer 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0, 
On exit, incx is unchanged, 

y Type complex. 

Array of dimension at least: 

\+{n-Vf\incy\. 

Before entry, the incremented array y must contain the n element vector y. 
On exit, y is unchanged 

incy Type integer. 

On entry, incy specifies the increment for the elements of y. 
Argument incy must not be 0. 
On exit, incy is unchanged. 
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a Type complex. 

Array of dimension (Ida, n). 

Before entry, the leading m-by-n part of array a must contain the matrix of coefficients. 
On exit, a is overwritten by the updated matrix. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 
Argument Ida must be at least max(l, m). 
On exit, Ida is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CGERU is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

CHBMV - Multiplies a complex vector by a complex Hermitian band matrix 
SYNOPSIS 

CALL CUBMV(uplo t nXalpha,aJdajwcx,beta,yMcy) 

DESCRIPTION 

CHBMV performs the following matrix-vector operation: 

y := alpha*a*x+beta*y 

Arguments alpha and beta are scalars, x and y are n element vectors, a is an n-by-n Hermitian band 
matrix, and k is a number of superdiagonals. 

uplo Type character* L 

On entry, trans specifies whether the upper or lower triangular part of band matrix a is being 
supplied as follows: 

If uplo = 'IT or 'u\ the upper triangular part of a is being supplied. 
If uplo = TL* or T, the lower triangular part of a is being supplied. 

On exit, uplo is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry, k specifies the number of superdiagonals of matrix a. 
Argument k must satisfy O.LEJfc. 
On exit, k is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

a Type complex. 

Array of dimension (Ida, n). 

Before entry with uplo = *IT or *u\ the leading (£+l)-by->i part of array a must contain the 
upper triangular band part of the Hermitian matrix, supplied column by column, with the lead- 
ing diagonal of the matrix in row (£+1) of the amy, the first superdiagonal starting at position 
2 in row K and so on. The top left k-by-k triangle of array a is not referenced. 

The following program segment will transfer the upper triangular part of a Hermitian band 
matrix from conventional full matrix storage to band storage: 

DO 20, J = 1, N 
M = K+ 1 - J 

DO 10, 1 = MAX( 1, J - K ), J 
A( M + I, J ) = MATRIX( I, J ) 
10 CONTINUE 
20 CONTINUE 
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Before entry with uplo « 'L* or T, the leading (i+l)-by-« part of array a must contain the 
lower triangular band part of the Hermitian matrix, supplied column by column, with the lead- 
ing diagonal of the matrix in row 1 of the array, the first subdiagonal starting at position 1 in 
row 2, and so on. The bottom right fc-by-jfc triangle of airay a is not referenced. 

The following program segment will transfer the lower triangular part of a Hermitian band 
matrix from conventional full matrix storage to band storage: 

DO 20, J = 1, N 
M= 1 - J 

DO 10, 1 = J, MIN( N, J + K ) 
A( M + I, J ) = MATRIX( I, J ) 
10 CONTINUE 
20 CONTINUE 

Note that the imaginary parts of the diagonal elements need not be set and are assumed to be 
0. 

On exit, a is unchanged. 
Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 
Argument Ida must be at least (k+l). 
On exit, Ida is unchanged. 

x Type complex. 

Array of dimension at least: 

l+(n~l)*\incx\. 

Before entry, the incremented array x must contain vector jc. 
On exit, x is unchanged. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

beta Type complex. 

On entry, beta specifies the scalar beta. 
On exit, beta is unchanged 

y Type complex. 

Array of dimension at least: 

l+(n-l)*||jicy|. 

Before entry, the incremented array y must contain vector y. 
On exit, y is overwritten by updated vector y. 

incy Type integer. 

On entry, incy specifies the increment for the elements of y. 
Argument incy must not be 0. 
On exit, incy is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CHBMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 



SR-0113 



4-25 



D 



CHEMM (3COS) 



CHEMM (3COS) 



NAME 

CHEMM - Multiplies a complex general matrix by a complex Herrnitian matrix 
SYNOPSIS 

CALL CHEMM(side t uph 1 m,n f alpha t a t lda l b i ldb t beta l c t ldc) 
DESCRIPTION 

CHEMM performs one of the following matrix-matrix operations: 

c := alpha*a*b+beta*c 
or c := alpha*b*a+beta*c 

Arguments alpha and beta are scalars, a is a Herrnitian matrix, and b and c are m-by-n matrices. 

side Type character* 1. 

On entry, side specifies whether the Herrnitian matrix a appears on the left or right in the 
operation as follows: 

If side = 'L* or T, c := alpha*a*b+beta*c 
If side = 'R* or *r\ c := alpha*b*a+beta*c 

On exit, side is unchanged. 
uplv Type character* 1. 

On entry, uplo specifies whether the upper or lower triangular part of the Herrnitian matrix is to 
be referenced as follows: 

If uplo = *IT or V, only the upper triangular part of the Herrnitian matrix is to be referenced. 
If uplo = *L' or T, only the lower triangular part of the Herrnitian matrix is to be referenced. 

On exit, uplo is unchanged. 

m Type integer. 

On entry, m specifies the number of rows in matrix c. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 
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a Type complex. 

Array of dimension (Ida, ka). 

ka is m when side - 'L* or T, and is n otherwise. 

Before entry with side = *L' or T, the m-by-m part of array a must contain the Hermitian 
matrix, such that: 

If uplo = 'U* or 'u\ the leading m-by-m upper triangular part of array a must contain the upper 

triangular part of the Hermitian matrix. 

The strictly lower triangular part of a is not referenced. 

If uplo - 'L* or T, the leading m-by-m lower triangular part of array a must contain the lower 

triangular part of the Hermitian matrix. 

The strictly upper triangular part of a is not referenced. 

Before entry with side = *R* or Y, the n-by-n part of array a must contain the Hermitian 
matrix, such that: 

If uplo = 'IT or V, the leading n-by-n upper triangular part of array a must contain the upper 

triangular part of the Hermitian matrix. 

The strictly lower triangular part of a is not referenced. 

If uplo = *L' or T, the leading n-by-n lower triangular part of array a must contain the lower 

triangular part of the Hermitian matrix. 

The strictly upper triangular part of a is not referenced. 

Note that the imaginary parts of the diagonal elements need not be set. They are assumed to 
be 0. 

On exit, a is unchanged. 
Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
When side = *L' or T, Ida must be at least max(l, m). 
Otherwise, Ida must be at least max(l, n). 
On exit, Ida is unchanged. 

b Type complex. 

Array of dimension (Idb, n). 

Before entry, the leading m-by-n part of array b must contain matrix 6, 
On exit, b is unchanged. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (subprogram. 
Argument Idb must be at least max(l, m). 
On exit, Idb is unchanged. 

beta Type complex. 

On entry, beta specifies the scalar beta. 

When beta is supplied as 0, c need not be set on input 

On exit, beta is unchanged. 

c Type complex. 

Array of dimension (ldc f n). 

Before entry, the leading m-by-n part of array c must contain matrix c, except when beta is 0, 

in which case c need not be set on entry. 

On exit, array c is overwritten by the m-by-n updated matrix. 



SR-0113 



4-27 



D 



CHEMMC3COS) 



CHEMM(3COS) 



Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (subprogram. 
Argument Idc must be at least max(l, m). 
On exit, Idc is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CHEMM is a level 3 Basic Linear Algebra Subprogram (BIAS 3). 
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NAME 

CHEMV - Multiplies a complex vector by a complex Hermitian matrix 
SYNOPSIS 

CALL CUEMViupto^alpha^Jda^dncxMetajMcy) 

DESCRIPTION 

CHEMV performs the following matrix-vector operation: 

y := alpha* a*x+beia*y 

Arguments alpha and beta are scalars, x and y are n element vectors, and a is an n-by-n Hermitian 
matrix. 

uplo Type character* 1. 

On entry, uplo specifies whether the upper or lower triangular part of array a is to be refer- 
enced as follows: 

If uplo- XT or V, only the upper triangular part of a is to be referenced. 
If uplo= 'L* or T, only the lower triangular part of a is to be referenced. 

On exit, uplo is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

a Type complex. 

Array of dimension (Ida, n). 

Before entry with uplo = 'IT or V, the leading n-by-n upper triangular part of array a must 
contain the upper triangular part of the Hermitian matrix. 
The strictly lower triangular part of a is not referenced. 

Before entry with uplo = 'L* or T, the leading n-by-n lower triangular part of array a must 
contain the lower triangular part of the Hermitian matrix. 
The strictly upper triangular part of a is not referenced. 

Note that the imaginary parts of the diagonal elements need not be set and are assumed to be 
0. 

On exit, a is unchanged. 
Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
Argument Ida must be at least max(l, n). 
On exit, Ida is unchanged. 
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x Type complex. 

Array of dimension at least: 

l+(n-l)*|mc4 

Before entry, the incremented array x must contain the n element vector 
On exit, x is unchanged, 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

beta Type complex. 

On entry, beta specifies the scalar beta. 

If beta is supplied as 0, y need not be set on input. 

On exit, beta is unchanged. 

y Type complex. 

Array of dimension at least: 

l+(w-l)*|mcy|. 

Before entry, the incremented array y must contain n element vector y. 
On exit, y is overwritten by updated vector y. 

incy Type integer. 

On entry, incy specifies the increment for the elements of y. 
Argument incy must not be 0. 
On exit, incy is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CHEMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

CHER - Performs Hermitian rank 1 update of a complex Hermitian matrix 

SYNOPSIS 

CALL CftER(uplo t n t alphajc f incx,a,lda) 

DESCRIPTION 

CHER performs the following Hermitian rank 1 operation: 

a := alpha*x*conjg(x')+a 

Argument alpha is a real scalar, x is an n element vector, and a is an n-by-n Hermitian matrix. 

uplo Type character* 1 . 

On entry, uplo specifies whether the upper or lower triangular part of array a is to be refer- 
enced as follows: 

If uplo- TJ' or V, only the upper triangular part of a is to be referenced. 
If uplo= 'L* or T, only the lower triangular part of a is to be referenced. 

On exit, uplo is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

x Type complex. 

Array of dimension at least: 

l+(n-l)*|wc4 

Before entry, the incremented array x must contain the n element vector x. 
On exit, x is unchanged. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 
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a Type complex. 

Array of dimension (Ida, n). 

Before entry with uplo ~ 'U* or V, the leading n-by-n upper triangular part of array a must 
contain the upper triangular part of the Hermitian matrix. 
The strictly lower triangular part of a is not referenced. 

On exit, the upper triangular part of array a is overwritten by the upper triangular part of the 
updated matrix. 

Before entry with uplo = *L* or T, the leading n-by-n lower triangular part of array a must 
contain the lower triangular part of the Hermitian matrix. 
The strictly upper triangular part of a is not referenced 

On exit, the lower triangular part of array a is overwritten by the lower triangular part of the 
updated matrix. 

Note that the imaginary parts of the diagonal elements need not be set and are assumed to be 
0. On exit, they are set to 0. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 
Argument Ida must be at least max(l, n). 
On exit, Ida is unchanged 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CHER is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

CHER2 - Performs Hermitian rank 2 update of a complex Hermitian matrix 
SYNOPSIS 

CALL CBER2(uplo,n t alphax>incx t yjncy,aJda) 

DESCRIPTION 

CHER2 performs the following Hermitian rank 2 operation; 

a := a/p^*jc*conjg(y')+conjg(a/p/w)*3^conjg(jc , )+a 

Argument alpha is a scalar, x and y are n element vectors, and a is an n-by-n Hermitian matrix. 

uplo Type character* 1 . 

On entry, uplo specifies whether the upper or lower triangular part of array a is to be refer- 
enced as follows: 

If uplo- *ir or V, only the upper triangular part of a is to be referenced. 
If uplo= 'L' or T, only the lower triangular part of a is to be referenced. 

On exit, uplo is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

x Type complex. 

Array of dimension at least: 

l+(rt-l)*|mcx|. 

Before entry, the incremented array x must contain the n element vector jc. 
On exit, x is unchanged. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

y Type complex. 

Array of dimension at least: 

l-K/i-l)*|/ncy|. 

Before entry, the incremented array y must contain the n element vector y. 
On exit, y is unchanged. 

incy Type integer. 

On entry, incy specifies the increment for the elements of y. 
Argument incy must not be 0. 
On exit, incy is unchanged. 
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a Type complex. 

Array of dimension (Ida, n). 

Before entry with uplo = *U* or V, the leading n-by-n upper triangular part of array a must 
contain the upper triangular part of the Hermitian matrix. 
The strictly lower triangular part of a is not referenced. 

On exit, the upper triangular part of array a is overwritten by the upper triangular part of the 
updated matrix. 

Before entry with uplo = *L' or T, the leading n-by-n lower triangular part of array a must 
contain the lower triangular part of the Hermitian matrix. 
The strictly upper triangular part of a is not referenced. 

On exit, the lower triangular part of array a is overwritten by the lower triangular part of the 
updated matrix. 

Note that the imaginary parts of the diagonal elements need not be set and are assumed to be 
0. On exit, they are set to 0. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
Argument Ida must be at least max(l, n). 
On exit, Ida is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CHER2 is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

CHER2K - Performs Hermitian rank 2k update of a complex Hermitian matrix 
SYNOPSIS 

CALL CHER2K(uplo s trans,n,k,alpha t a t lda t bJdb t beta t c,ldc) 
DESCRIPTION 

CHER2K performs one of the following Hermitian rank 2k operations: 
c := alpha*a*a3n}g(b')+cm}g(atpha)*b*conjg(a')+beta*c 
or 

c alpha^Qonjgia'^bwonjgialpha^conjgib^^a^beta^c. 

Arguments alpha and beta are scalars with beta real, and c is an n-by-n Hermitian matrix. Arguments 
a and b are n-by-k matrices in the first operation listed previously, and k-by-n matrices in the second. 

uplo Type character* 1 . 

On entry, uplo specifies whether the upper or lower triangular part of array c is to be refer- 
enced as follows: 

If uplo = 'U* or V, only the upper triangular part of c is to be referenced. 
If uplo = 'L* or T, only the lower triangular part of c is to be referenced. 

On exit, uplo is unchanged. 

trans Type character* 1. 

On entry, trans specifies the operation to be performed as follows: 

If trans = 'NT or V, 

c := alpha*a*oon]g(b , )rt;on}g(alpha)*b*con}g{a t )+beta*c. 
If trans - *C or V, 

c := alpha*conjg(a')*bH:on}g(alpha)*cot\}g(b i )*a+beta*c. 

On exit, trans is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry with trans - 'N' or V, k specifies the number of columns of matrices a and b. 
On entry with trans = 'C or V, k specifies the number of rows of matrices a and b. 

Argument k must be at least 0. 
On exit, k is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 
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a Type complex. 

Array of dimension (Ida, ka). 

Argument ka is k if trans = 'N* or 'n\ and is n otherwise. 

Before entry with trans = 'N* or *n\ the leading /i-by-it part of array a must contain matrix a. 
Otherwise, the leading t-by-n part of army a must contain matrix a. 

On exit, a is unchanged 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 

If trans = *N* or V, Ida must be at least max(l, n). 
Otherwise, Ida must be at least max(l, k). 

On exit, Ida is unchanged. 

b Type complex. 

Array of dimension (Idb, kb) 

Argument kb is k if trans ~ *N* or *n\ and is n otherwise. 

Before entry with trans = *N* or 'n\ the leading n-by-A part of array b must contain matrix i. 
Otherwise, the leading t-by-n part of array b must contain matrix b. 

On exit, b is unchanged. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling(sub) program. 
If trans = 'N* or *n\ Idb must be at least max(l, 71). 
Otherwise, Idb must be at least max(l, k). 
On exit, Idb is unchanged. 

beta Type real. 

On entry, beta specifies the scalar beta. 
On exit, beta is unchanged. 

c Type complex. 

Array of dimension (Idc, n). 

Before entry with uplo = 'LP or V, the leading n-by-n upper triangular part of array c must 
contain the upper triangular part of the Hermitian matrix. 
The strictly lower triangular part of c is not referenced. 

On exit, the upper triangular part of array c is overwritten by the upper triangular part of the 
updated matrix. 

Before entry with uplo = X* or T, the leading n by n lower triangular part of array c must 
contain the lower triangular part of the Hermitian matrix. 
The strictly upper triangular part of c is not referenced* 

On exit, the lower triangular part of array c is overwritten by the lower triangular part of the 
updated matrix. 

Note that the imaginary parts of the diagonal elements need not be set and are assumed to be 
0* On exit, they are set to 0. 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (sub)program. 
Argument Idc must be at least max(l, 
On exit, Idc is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NOTE 

CHER2K is a level 3 Basic Linear Algebra Subprogram (BIAS 3). 
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NAME 

CHERK - Performs Hermitian rank k update of a complex Hermitian matrix 
SYNOPSIS 

CALL CHERK(up/o .trans f n,k,alpha,a,lda,beta,c,ldc) 
DESCRIPTION 

CHERK performs one of the following Hermitian rank k operations: 
c := alpha*a*coxi}g(a')+beta*c 
or 

c := alpha*con}g(a')*a+beta*c. 

Arguments alpha and beta are real scalars, and c is an n-by-n Hermitian matrix. Argument a is 
an n-by-jfc matrix in the first operation listed previously, and a k-by-n matrix in the second. 

uplo Type character* 1. 

On entry, uplo specifies whether the upper or lower triangular part of array c is to be refer- 
enced as follows: 

If uplo = *tF or V, only the upper triangular part of c is to be referenced. 
If uplo = 1/ or T, only the lower triangular part of c is to be referenced. 

On exit uplo is unchanged, 

trans Type character*!. 

On entry, trans specifies the operation to be performed as follows: 

If trans = 'N* or V, 

c := alpha*a*cori}g(a')+beta*c. 

If trans - 'C or 'c\ 

c := alpha*con}g(a*)*a+beta*c. 

On exit, trans is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry with trans = 'N* or *n\ k specifies the number of columns of matrix a. 
On entry with trans = 'C* or 'c\ k specifies the number of rows of matrix a. 

Argument k must be at least 0. 
On exit, k is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 
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a Type complex. 

Array of dimension (lda 9 ka). 

Argument ka is k if trans = *N* or *n\ and is n otherwise. 

Before entry with trans = *N* or *n\ the leading n-by-k part of array a must contain matrix a. 
Otherwise, the leading k-by-n part of array a must contain matrix a. 

On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 

If trans = 5 N* or *n\ Ida must be at least max(l, n). 
Otherwise, Ida must be at least max(l, k). 

On exit, Ida is unchanged. 

beta Type real. 

On entry, beta specifies the scalar beta. 
On exit, beta is unchanged. 

c Type complex. 

Array of dimension (Idc, n). 

Before entry with upto = TP or *u\ the leading n-by-n upper triangular part of array c must 
contain the upper triangular part of the Hermitian matrix. 
The strictly lower triangular part of c is not referenced. 

On exit, the upper triangular part of array c is overwritten by the upper triangular part of the 
updated matrix. 

Before entry with uplo = *L' or T, the leading n-by-n lower triangular part of array c must 
contain the lower triangular part of the Hermitian matrix. 
The strictly upper triangular part of c is not referenced. 

On exit, the lower triangular part of array c is overwritten by the lower triangular part of the 
updated matrix. 

Note that the imaginary parts of the diagonal elements need not be set and are assumed to be 
0. On exit, they are set to 0. 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (sub)program. 
Argument Idc must be at least max(l, n). 
On exit, Idc is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CHERK is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 



SR-0113 



4-39 



D 



CROT(3SCI) 



CROT(3SCI) 



NAME 

CROT - Applies the complex plane rotation computed by CROTG 

SYNOPSIS 

CALL CROT(n,cx,incx,cy4ncy,sc,cs) 

DESCRIPTION 



n Number of vector elements on which to apply rotation (input) 

cx Complex array of length at least l+(/i4)*jmcjc| containing vector to be modified 
(input/output) 

incx Increment between vector elements in cx (input) 

cy Complex vector to be modified, of length at least l+(n-l)*|z/icy| (input/output) 

incy Increment between vector elements in cy (input) 

sc Real cosine of rotation (computed by CROTG) (input) 

cs Complex sine of rotation (computed by CROTG) (input) 



CROT applies the following complex plane rotation to row vectors cx and cy: 

\cxx~\ _ [ sc cs] Icjc] 
[cyyi \rccs sc] kyj 

where cxx and cyy are the resulting complex row vectors, overwriting cx and cy t and ccs is the complex 
conjugate of cs. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems, 

SEE ALSO 

CROTG(3SCI), SROT(3SO) 
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NAME 

CROTG - Constructs a Givens plane rotation 

SYNOPSIS 

CALL CROTG(ca,cb,sc,cs) 

DESCRIPTION 

ca First complex element of the two-element vector that determines the angle of rotation 

(input/output) 

cb Second complex element of the two-element vector that determines the angle of rotation 

(input/output) 

sc Real cosine of the rotation (output) 

cs Complex sine of the rotation (output) 

CROTG computes the elements of a complex Givens plane rotation matrix such that: 

[cm] _ [ sc cs] leal 
, 0 J " l-ccs sc} [cb\ 

where cca overwrites ca y cb remains unchanged, and ccs is the complex conjugate of cs. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems* 

SEE ALSO 

CROT(3SCI) f SROT(3SCI) 
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NAME 

CSYMM - Multiplies a complex general matrix by a complex symmetric matrix 
SYNOPSIS 

CALL CSYMM(sideMplo,m,n,alpha,a,lda,b,ldb t beta t c t ldc) 
DESCRIPTION 

CSYMM performs one of the following matrix-matrix operations: 

c := alpha*a*b+beta*c 
or c := alpha*b*a+beta*c 

Arguments alpha and beta are scalars, a is a symmetric matrix, and b and c are m-by-n matrices, 

side Type character* 1, 

On entry, side specifies whether the symmetric matrix a appears on the left or right in the 
operation as follows: 

If side = 'L' or T\ c := alpha*a*b+beta*c 
If side = 'R' or V, c := alpha*b*a+beta*c 

On exit, side is unchanged. 

uplo Type character* 1. 

On entry, uplo specifies whether the upper or lower triangular part of the symmetric matrix a is 
to be referenced as follows: 

If uplo = IT or V, only the upper triangular part of the symmetric matrix is to be referenced. 
If uplo = *L* or T, only the lower triangular part of the symmetric matrix is to be referenced. 

On exit, uplo is unchanged. 

m Type integer. 

On entry, m specifies the number of rows in matrix c. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 
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a Type complex. 

Array of dimension (Ida* ka). 

Argument ka is m when side = *L* or T, and is n otherwise. 

Before entry with side - X* or T, the m-by-m part of array a must contain the symmetric 
matrix, such that: 

If uplo = 'U* or 'u\ the leading m-by-m upper triangular part of array a must contain the upper 

triangular part of the symmetric matrix. 

The strictly lower triangular part of a is not referenced. 

If uplo = 'L* or T, the leading m-by-m lower triangular part of array a must contain the lower 

triangular part of the symmetric matrix. 

The strictly upper triangular part of a is not referenced. 

Before entry with side - *R* or Y, the n-by-n part of array a must contain the symmetric 
matrix, such that: 

If uplo - 'U* or *u\ the leading n-by-n upper triangular part of array a must contain the upper 

triangular part of the symmetric matrix. 

The strictly lower triangular part of a is not referenced. 

If uplo = *L* or V, the leading n-by-n lower triangular part of array a must contain the lower 

triangular part of the symmetric matrix. 

The strictly upper triangular part of a is not referenced. 

On exit, a is unchanged. 
Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 
When side = 1/ or T, Ida must be at least max(l, m). 
Otherwise, Ida must be at least max(l, n). 
On exit, Ida is unchanged. 

b Type complex. 

Array of dimension (Idb, n). 

Before entry, the leading m-by-n part of array b must contain matrix b. 
On exit, b is unchanged. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (subprogram. 
Argument Idb must be at least max(l, m). 
On exit, Idb is unchanged. 

beta Type complex. 

On entry, beta specifies the scalar beta. 

When beta is supplied as 0, c need not be set on input. 

On exit, beta is unchanged. 

c Type complex. 

Array of dimension (Idc, n). 

Before entry, the leading m-by-n part of array c must contain matrix c, except when beta is 0, 

in which case c need not be set on entry. 

On exit, array c is overwritten by the m-by-n updated matrix. 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (subprogram. 
Argument Idc must be at least max(l, m). 
On exit, Idc is unchanged. 
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IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CSYMM is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 
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NAME 

CSYR2K - Performs symmetric rank 2k update of a complex symmetric matrix 
SYNOPSIS 

CALL CSYR2K(uphjrans t nfaalpha t aJda>bJdbMta£,tdc) 
DESCRIPTION 

CSYR2K performs one of the following symmetric rank 2k operations: 
c := alpha*a*b f +alpha*b*a' +beta*c 
or 

c := alpha*a'*b+alpha ¥ b**a+beta*c 

Arguments alpha and beta are scalars, and c is an n-by-n symmetric matrix. Arguments a and b 
are n-by-k matrices in the first operation listed previously, and Jk-by-w matrices in the second. 

uplo Type character* 1. 

On entry, uplo specifies whether the upper or lower triangular part of array c is to be refer- 
enced as follows: 

If uplo a V* or V, only the upper triangular part of c is to be referenced. 
If uplo = X' or T, only the lower triangular part of c is to be referenced. 

On exit, uplo is unchanged. 

trans Type character* L 

On entry, trans specifies the operation to be performed as follows: 

If trans = *N* or V, 

c := alpha*a*b* +alpha*b*a 9 +beta*c 

If trans = T or Y, 

c := alpha*a'*b+alpha*b'*a+beta*c 

On exit, trans is unchanged 

n Type integer. 

On entry, n specifies the order of matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry with trans = 'N' or *n\ k specifies the number of columns of matrices a and b. 
On entry with trans = T' or Y, k specifies the number of rows of matrices a and /?. 

Argument k must be at least 0. 
On exit, k is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 
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a Type complex. 

Array of dimension (tda> ka). 

Argument ka is k if trans = *N f or V, and is n otherwise. 

Before entry with trans = 'N* or V, the leading n-by-k part of array a must contain matrix a. 
Otherwise, the leading k-by-n part of array a must contain matrix a. 

On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 

If trans = *N' or *n\ Ida must be at least max(I, n). 
Otherwise, Ida must be at least max(l, £). 

On exit, Ida is unchanged. 

b Type complex. 

Array of dimension (ldb y kb) 

Argument kb is k if trans - *N* or *n\ and is n otherwise. 

Before entry with trans = f N' or 'n\ the leading n-by-k part of array b must contain matrix fc. 
Otherwise, the leading k-by-n part of array b must contain matrix b. 

On exit, 6 is unchanged. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (subprogram. 

If trans = *N' or 'n\ Idb must be at least max(l, n). 
Otherwise, Idb must be at least max(l, k). 

On exit, Idb is unchanged. 

beta Type complex. 

On entry, beta specifies the scalar beta. 
On exit, beta is unchanged. 

c Type complex. 

Array of dimension (Idc, n). 

Before entry with uplo = 'IT or V, the leading n-by-n upper triangular part of array c must 
contain the upper triangular part of the symmetric matrix. 
The strictly lower triangular part of c is not referenced. 

On exit, the upper triangular part of array c is overwritten by the upper triangular part of the 
updated matrix. 

Before entry with uplo = *L' or T, the leading n-by-/i lower triangular part of array c must 
contain the lower triangular part of the symmetric matrix. 
The strictly upper triangular part of c is not referenced. 

On exit, the lower triangular part of array c is overwritten by the lower triangular part of the 
updated matrix. 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (subprogram. 
Argument Idc must be at least max(l, n). 
On exit, Idc is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NOTE 

CSYR2K is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 
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NAME 

CSYRK - Performs symmetric rank k update of a complex symmetric matrix 
SYNOPSIS 

CALL CSYRK(uplo t trans t n l k t alpha t aJda f beta t cJdc) 
DESCRIPTION 

CSYRK performs one of the following symmetric rank k operations: 
c := alpha*a*a l +beta*c 
or 

c := alpha*a**a+beta*c 

Arguments alpha and beta are scalars, and c is an n-by-n symmetric matrix. Argument a is an n-by-ifc 
matrix in the first operation listed previously, and a Jt-by-n matrix in the second. 

uplo Type character*!. 

On entry, uplo specifies whether the upper or lower triangular part of array c is to be refer- 
enced as follows: 

If uplo - 'U' or V, only the upper triangular part of c is to be referenced. 
If uplo = X* or T, only the lower triangular part of c is to be referenced. 

On exit, uplo is unchanged. 

trans Type character* 1. 

On entry, trans specifies the operation to be performed as follows: 

If trans = 'N' or V, 

c := alpha*a*a* +beta*c. 

If trans = T' or Y, 

c := alpha*a'*a+beta*c. 

On exit, trans is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry with trans - *N* or V, k specifies the number of columns of matrix a. 
On entry with trans = T* or Y, k specifies the number of rows of matrix a. 

Argument k must be at least 0. 
On exit, k is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 
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a Type complex. 

Array of dimension (Ida, ka). 

Argument ka is k if trans - *N* or f n\ and is n otherwise. 

Before entry with trans = *N* or *n\ the leading n~by-k part of array a must contain matrix a. 
Otherwise, the leading k-by-n part of array a must contain matrix a. 

On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 

If trans = 'N* or V, Wtf must be at least max(l, n). 
Otherwise, Ida must be at least max(l, k). 

On exit, Ida is unchanged. 

teta Type complex. 

On entry, beta specifies the scalar beta. 
On exit, beta is unchanged. 

c Type complex. 

Array of dimension (Idc, n). 

Before entry with uplo = *U' or 'u\ the leading n-by~n upper triangular part of array c must 
contain the upper triangular part of the symmetric matrix. 
The strictly lower triangular part of c is not referenced. 

On exit, the upper triangular part of array c is overwritten by the upper triangular part of the 
updated matrix. 

Before entry with uplo = 'L/ or T, the leading n-by-n lower triangular part of array c must 
contain the lower triangular part of the symmetric matrix. 
The strictly upper triangular part of c is not referenced. 

On exit, the lower triangular part of array c is overwritten by the lower triangular part of the 
updated matrix. 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (sub)piogram. 
Argument Idc must be at least max(l, n). 
On exit, Idc is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CSYRK is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 
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NAME 

CTBMV - Multiplies a complex vector by a complex triangular band matrix 
SYNOPSIS 

CALL CTBMV(uplo t trans t diag t n,k t a t lda>x t incx) 
DESCRIPTION 

CTBMV performs one of the following matrix-vector operations: 
x := a*x 
or x := a'*x 
or x := conjg(a')*x 

Argument x is an n element vector, and a is an n-by-n unit, or non-unit, upper or lower triangular band 
matrix, with (£+1) diagonals. 

uplo Type character*!. 

On entry, uplo specifies whether the matrix is an upper or lower triangular matrix as follows: 

If uplo = *U' or V, a is an upper triangular matrix. 
If uplo - *L' or T, a is a lower triangular matrix. 

On exit, uplo is unchanged. 

trans Type character *1. 

On entry, trans specifies the operation to be performed as follows: 

If trans = *N' or f n\ x := 

If trans = T or *t\ x := a'*x. 

If trans = 'C* or *c\ x := conjg(a')*x. 

On exit, trans is unchanged. 

diag Type character * 1 . 

On entry, diag specifies whether or not a is unit triangular as follows: 

If diag = 'U' or 'u\ a is assumed to be unit triangular. 
If diag = 'N' or V, a is not assumed to be unit triangular. 

On exit, diag is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry with uplo = *LP or *u\ k specifies the number of superdiagonals of matrix a. 
On entry with uplo = or T, k specifies the number of subdiagonals of matrix a. 

Argument it must satisfy O.LE.£. 
On exit, k is unchanged. 
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a Type complex. 

Array of dimension (lda> n). 

Before entry with uplo = *U' or *u\ the leading (£+l)~by-n part of array a must contain the 
upper triangular band part of the matrix of coefficients, supplied column by column, with the 
leading diagonal of the matrix in row (£+1) of the array, the first superdiagonal starting at posi- 
tion 2 in row k f and so on. The top left k-by-k triangle of array a is not referenced. 

The following program segment will transfer an upper triangular band matrix from conven- 
tional full matrix storage to band storage: 

DO 20, J = 1, N 
M = K + 1 - J 

DO 10, 1 = MAX( 1, J - K ), J 
A( M + I, J ) = MATRIX( I, J ) 
10 CONTINUE 
20 CONTINUE 

Before entry with uplo = 'L' or T, the leading (£+I)-by-?i part of array a must contain the 
lower triangular band part of the matrix of coefficients, supplied column by column, with the 
leading diagonal of the matrix in row 1 of the array, the first subdiagonal starting at position 1 
in row 2, and so on. The bottom right k-by-k triangle of array a is not referenced. 

The following program segment will transfer a lower triangular band matrix from conventional 
full matrix storage to band storage: 

DO 20, J = 1, N 
M= 1 - J 

DO 10, 1 = J, MIN( N, J + K ) 
A( M + I, J ) = MATRIX( I, J ) 
10 CONTINUE 
20 CONTINUE 

Note that when diag - *U* or 'u\ the elements of array a corresponding to the diagonal ele- 
ments of the matrix are not referenced, but are assumed to be unity. 

On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 
Argument Ida must be at least (k+ 1). 
On exit, Ida is unchanged, 

x Type complex. 

Array of dimension at least: 

l+(n-l)*\incx\. 

Before entry, the incremented array x must contain the n element vector x. 
On exit, x is overwritten with the transformed vector x. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NOTE 

CTBMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

CTBSV - Solves a complex triangular banded system of equations 
SYNOPSIS 

CALL CTBSy(uplo t trans4iag t nJc f a f lda t xMcx) 

DESCRIPTION 

CTBSV solves one of the following systems of equations: 

a*x = b 

or a**x = b 

or conjg(a')*x » b 

Arguments x and b are n element vectors, and a is an n-by-n unit, cm* non-unit, upper or lower triangular 
band matrix, with (fc+1) diagonals, 

uplo Type character* 1. 

On entry, uplo specifies whether the matrix is an upper or lower triangular matrix as follows: 

If uplo - TJ* or V, a is an upper triangular matrix. 
If uplo - *L* or T, a is a lower triangular matrix. 

On exit, uplo is unchanged. 

trans Type character *1. 

On entry, trans specifies the operation to be performed as follows: 

If trans = *N' or V, a*x = b 
If trans = TT or 't\ a'*x = b 
If trans = f C f or V, conjg(a')** = b 

On exit, trans is unchanged. 

diag Type character * 1 . 

On entry, diag specifies whether or not a is unit triangular as follows: 

If diag = 'U' or V, a is assumed to be unit triangular. 
If diag = *N* or V, a is not assumed to be unit triangular. 

On exit, diag is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry with uplo - *LT or f u\ k specifies the number of superdiagonals of matrix a. 
On entry with uplo - 'L' or T, k specifies the number of subdiagonals of matrix a. 

Argument k must satisfy 
On exit, k is unchanged. 
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a Type complex. 

Array of dimension {Ida, n). 

Before entry with uplo = 'U* or V, the leading (Jfc+l)-by-* part of array a must contain the 
upper triangular band part of the matrix of coefficients, supplied column by column, with the 
leading diagonal of the matrix in row (£+1) of the array, the first superdiagonal starting at posi- 
tion 2 in row k 9 and so on. The top left k-by-k triangle of array a is not referenced. 

The following program segment will transfer an upper triangular band matrix from conven- 
tional full matrix storage to band storage: 

DO 20, J = 1, N 
M= K + 1 - J 

DOIO^I-MAXCM-KXJ 
A( M + I, J ) = MATRIX( I, J ) 
10 CONTINUE 
20 CONTINUE 

Before entry with uplo = *L* or T, the leading (jfc+l)-by-n part of array a must contain the 
lower triangular band part of the matrix of coefficients, supplied column by column, with the 
leading diagonal of the matrix in row 1 of the array, the first subdiagonal starting at position 1 
in row 2, and so on. The bottom right k-by-k triangle of array a is not referenced. 

The following program segment will transfer a lower triangular band matrix from conventional 
full matrix storage to band storage: 

DO 20, J = 1, N 
M= 1 - J 

DO 10, 1 = J, MIN( N, J + K ) 
A( M + I, J ) = MATRIX( I, J ) 
10 CONTINUE 
20 CONTINUE 

Note that when diag = *U* or 'u\ the elements of array a corresponding to the diagonal ele- 
ments of the matrix are not referenced, but are assumed to be unity. 

On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
Argument Ida must be at least (£+1). 
On exit, Ida is unchanged. 

x Type complex. 

Array of dimension at least: 

l+(n-\)*\incx\. 

Before entry, the incremented array x must contain the n element right-hand side vector b. 
On exit, x is overwritten with the solution vector x. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NOTES 

No tests for singularity or near-singularity arc included in CTBSV. Such tests must be performed before 
calling this routine. 

CTBSV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

CTRMM - Multiplies a complex genial matrix by a complex triangular matrix 
SYNOPSIS 

CALL CTRMMiside.uplo^transaMiag^n^tpha^Jda^Jdb) 

DESCRIPTION 

CTRMM performs one of the matrix-matrix operations: 

b := alpha*op(a)*b 

or b := alpha*b*op(a) 

Argument alpha is a scalar, b is an m-by-n matrix, 

a is a unit, or non-unit, upper or lower triangular matrix, 

and op(a) is one of the following: 

op(a) = a, 

or op(a) = a\ 

or op(a) = conjg(a') 



side Type character 4 ' 1. 

On entry, side specifies whether op(a) multiplies b from the left or right as follows: 

If side = *L* or T, b := alpha*op(a)*b. 
If side = *R* or V, b := alpha* b*op(a). 

On exit, rafe is unchanged. 

uplo Type character* L 

On entry, uplo specifies whether matrix (a) is an upper or lower triangular matrix as follows: 

If uplo = 'IT or 'u\ a is an upper triangular matrix. 
If uplo = 1/ or T, a is a lower triangular matrix. 

On exit, uplo is unchanged. 

transa Type character* 1 . 

On entry, transa specifies the form of op(a) to be used in the matrix multiplication as follows: 

If transa = *N* or *n\ op(a) = a. 
If transa - T or V, op(a) - a'. 
If /mora = *C or 'c\ op(a) = conjg(a'). 

On exit, transa is unchanged. 

diag Type character* 1 . 

On entry, diag specifies whether or not a is unit triangular as follows: 

If diag ~ 'U* or V, a is assumed to be unit triangular. 
If diag = 'N' or 'n\ a is not assumed to be unit triangular. 

On exit, diag is unchanged. 
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m Type integer. 

On entry, m specifies the number of rows in b. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in 6. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 

When alpha is 0, a is not referenced, and b need not be set before entry. 
On exit, alpha is unchanged* 

a Type complex. 

Array of dimension (Ida, k). 

Argument k is m when side = *L* or T, and is n when side = *R' or Y. 

Before entry with uplo - *IT or *u\ the leading k-hy-k upper triangular part of array a must 

contain the upper triangular matrix. 

Hie strictly lower triangular part of a is not referenced. 

Before entry with uplo = *L* or T, the leading k-hy-k lower triangular part of array a must 

contain the lower triangular matrix. 

The strictly upper triangular part of a is not referenced. 

Note that when diag = TT or 'u\ the diagonal elements of a are not referenced, but are 
assumed to be unity. 
On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
When side * 'L* or T, Ida must be at least max(l, m). 
When side = 'R* or Y, Ida must be at least max(l, *). 
On exit, Ida is unchanged. 

b Type complex. 

Array of dimension (Idb, n). 

Before entry, the leading m-by-n part of array b must contain matrix fc. 
On exit, b is overwritten by the transformed matrix, 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (sub)program. 
Argument Idb must be at least max(l, m). 
On exit, Idb is unchanged 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CTRMM is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 
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NAME 

CTRMV - Multiplies a complex vector by a complex triangular matrix 
SYNOPSIS 

CALL CTRMV(uplo,trans,diag t n t a t tda t x t incx) 
DESCRIPTION 

CTRMV performs one of the following matrix-vector operations: 
x := a*x 
or x a! *x 
or x :~ conjg(a')** 

Argument x is an n element vector, and a is an «-by-/i unit, or non-unit, upper or lower triangular 
matrix. 

uplo Type character* 1. 

On entry, uplo specifies whether the matrix is an upper or lower triangular matrix as follows: 

If uplo = *U* or V, a is an upper triangular matrix. 
If uplo - 'L* or T, a is a lower triangular matrix. 

On exit, uplo is unchanged. 

trans Type character *1. 

On entry, trans specifies the operation to be performed as follows: 

If trans = 'N' or *n\ x :- a*x. 
If trans = T* or 't\ x := a'**. 
If trans = 'C or 'c\ x conjg(a')*jc. 

On exit, trans is unchanged, 

diag Type character * 1 . 

On entry, diag specifies whether or not a is unit triangular as follows: 

If diag =s TT or V, a is assumed to be unit triangular. 
If diag - 'N' or 'n\ a is not assumed to be unit triangular. 

On exit, diag is unchanged, 

n Type integer. 

On entry, n specifies the order of matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 
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a Type complex. 

Array of dimension (Ida* n). 

Before entry with uplo = 'U' or *u\ the leading n-by-n upper triangular part of array a must 

contain the upper triangular matrix. 

The strictly lower triangular part of a is not referenced. 

Before entry with uplo = *L* or T, the leading n-by-n lower triangular part of array a must 

contain the lower triangular matrix. 

The strictly upper triangular part of a is not referenced. 

Note that when diag « *U* or *u\ the diagonal elements of a are also not referenced, and are 
assumed to be unity. 

On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
Argument Ida must be at least max(l, n). 
On exit, Ida is unchanged. 

x Type complex. 

Array of dimension at least: 

l+(/i-l)*|mc4 

Before entry, the incremented array x must contain the n element vector x. 
On exit, x is overwritten with the transformed vector x. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CTRMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

CTRSM - Solves a complex triangular system of equations with multiple right-hand sides 
SYNOPSIS 

CALL CTRSM(side,uplo,transa4iag t m t nAlpha,a,lda>bJdb) 

DESCRIPTION 

CTRSM solves one of the following matrix equations: 

op(a)*Jc = alpha*b 

or x*op(a) = alpha*b 

Argument alpha is a scalar, x and b are m-by-n matrices, a is a unit, or non-unit, upper or lower tri- 
angular matrix, and op(a) is one of the following: 

op(a) = a, 

or op(a) = a', 

or op(a) = conjg(a') 

Matrix x is overwritten on b. 



side Type character* 1, 

On entry, side specifies whether op(a) appears on the left or right of x as follows: 

If side = 1/ or T, op(a)*x = alpha*b 
If side = 'R* or V, jt*op(a) = alpha*b 

On exit, side is unchanged. 

uplo Type character* 1. 

On entry, uplo specifies whether matrix (a) is an upper or lower triangular matrix as follows: 

If uplo = f U f or V, a is an upper triangular matrix. 
If uplo = *L' or T, a is a lower triangular matrix. 

On exit, uplo is unchanged. 

transa Type character* 1 . 

On entry, transa specifies the form of op(a) to be used in the matrix multiplication as follows: 

If transa = 'N* or *n\ op(a) = a. 
If transa = 9 T or V, op(a) = a\ 
If transa = *C or 'c\ op(a) = conjg(«')- 

On exit, transa is unchanged. 

diag Type character* 1 . 

On entry, diag specifies whether or not a is unit triangular as follows: 

If diag - 'IT or V, a is assumed to be unit triangular. 
If diag = 'N* or 'n\ a is not assumed to be unit triangular. 

On exit, diag is unchanged. 
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m Type integer. 

On entry, m specifies the number of rows in b. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in b. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type complex. 

On entry, alpha specifies the scalar alpha. 

When alpha is 0, a is not referenced, and b need not be set before entry. 
On exit, alpha is unchanged. 

a Type complex. 

Array of dimension (Ida, k). 

Argument k is m when side = *L' or T, and is n when side = *R' or Y. 

Before entry with uplo = *tT or *u\ the leading k-hy-k upper triangular part of array a must 

contain the upper triangular matrix. 

The strictly lower triangular part of a is not referenced. 

Before entry with uplo - 'L* or T, the leading k-hy-k lower triangular part of array a must 

contain the lower triangular matrix. 

The strictly upper triangular part of a is not referenced. 

Note that when diag = 'IT or *u\ the diagonal elements of a are not referenced, but are 
assumed to be unity. 
On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
When side = *L* or T, Ida must be at least max(l, m). 
When side = 'R* or Y, Ida must be at least max(l, n). 
On exit, Ida is unchanged 

b Type complex. 

Array of dimension (Idb, n). 

Before entry, the leading m-by-n part of array b must contain the right-hand side matrix b. 
On exit, b is overwritten by the solution matrix x. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (subprogram. 
Argument Idb must be at least max(l, m). 
On exit, Idb is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

CTRSM is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 
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NAME 

CTRSV - Solves a complex triangular system of equations 
SYNOPSIS 

CALL CTViS\{uplo t trans4iag t n t a t ldapc t incx) 

DESCRIPTION 

CTRSV solves one of the following systems of equations: 

a*x = b 

or a'*x = b 

or conjg(a')*x = b 

Arguments b and x are n element vectors, and a is an n-by-/t unit, or non-unit, upper or lower triangular 
matrix. 

uplo Type character* 1 . 

On entry, uplo specifies whether the matrix is an upper or lower triangular matrix as follows: 

If uplo = 'LP or V, a is an upper triangular matrix. 
If uplo = 'L* or T, a is a lower triangular matrix. 

On exit, uplo is unchanged. 

trans Type character *1. 

On entry, trans specifies the operation to be performed as follows: 

If trans = *N' or V, a*x = b 
If trans = T or V, <z'*x = b 
If trans = 'C or V, conjgfc')** = b 

On exit, trans is unchanged. 

diag Type character *1. 

On entry, diag specifies whether or not a is unit triangular as follows: 

If diag = 'IT or V, a is assumed to be unit triangular. 
If diag - 'N 1 or *n\ a is not assumed to be unit triangular. 

On exit, diag is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix a. 
Argument n must be at least 0. 
On exit, n is unchanged. 
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a Type complex. 

Array of dimension (Ida, n). 

Before entry with uplo = *U* or V, the leading n-by-n upper triangular part of array a must 

contain the upper triangular matrix. 

The strictly lower triangular part of a is not referenced. 

Before entry with uplo = 'L' or T, the leading n-by-n lower triangular part of array a must 

contain the lower triangular matrix. 

The strictly upper triangular part of a is not referenced. 

Note that when diag = 'U' or 'u\ the diagonal elements of a are also not referenced, and are 
assumed to be unity. 

On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 
Argument Ida must be at least max(l, n). 
On exit, Ida is unchanged. 

x Type complex. 

Array of dimension at least: 

l+(nA)*\incx\. 

Before entry, the incremented array x must contain the n element right-hand side vector b. 
On exit, x is overwritten with the solution vector jr. 

incx Type integer. 

On entry, incx specifies the increment for the elements of x. 
Argument incx must not be 0. 
On exit, incx is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTES 

No teste for singularity or near-singularity are included in CTRSV. Such tests must be performed before 
calling this routine. 

CTRSV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

SDOT, CDOTC, CDOTU - Computes a dot product (inner product) of two real or complex vectors 

SYNOPSIS 

dot = SDOT(n t sx,incx,sy,incy) 
cdot sr CUQTC(n,cx,incx,cy,incy) 
cdot = CDOTU(n t cxjncx t cy>incy) 

DESCRIPTION 



n Number of elements in each vector (input) 

sx Real vector operand of length at least \+(n-l)*\incx\ (input) 

cx Complex vector operand of length at least l+(n-l)*\incx\ (input) 

incx Increment between elements of x in sx or cx (input) 

sy Real vector operand of length at least l+(/i-l)*|mcy| (input) 

cy Complex vector operand of length at least l+(n-X)*\incy\ (input) 

incy Increment between elements of sy or cy (input) 



For contiguous elements, incy - I 
These real and complex functions compute an inner product erf two vectors. 
SDOT computes 

n 

1=1 

where Xi and yi are elements of real vectors. 
CDOTC computes 

n 

cdot = X 

where and jv are elements of complex vectors and % is the complex conjugate of . 
CDOTU computes 

n 

cdot = X Wi 
j=i 

where xi and ^ are elements of complex vectors. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

EISPACK - Single-precision EISPACK routines 
DESCRIPTION 

EISPACK is a package of Fortran routines for solving the eigenvalue problem and for computing and 
using the singular value decomposition. 

The original Fortran versions are documented in the Matrix Eigensystem Routines - EISPACK Guide, 
second edition, by B. T. Smith, J. M. Boyle, J. J. Dongarra, B. S. Garbow, Y. Dcebe, V. C Klema, and 
C, B. Moler, published by Springer- Verlag, New York, 1976, Library of Congress catalog card number 
76-2662 (available through Cray Research as publicaton S2-0113); and in the Matrix Eigensystem Rou- 
tines - EISPACK Guide Extension by B. S. Garbow, J. M. Boyle, J. J. Dongarra, and C. B. Moler, pub- 
lished by Springer- Verlag, New York, 1977, Library of Congress catalog card number 77-2802 (avail- 
able through Cray Research as publicaton S3-0113). 

Each scientific library version of the EISPACK routines has the same name, algorithm, and calling 
sequence as the original version. Optimization of each routine includes the following: 

• Use of the BLAS routines SDOT, SASUM, SNRM2, ISAMAX, and ISMIN where applicable 

• Removal of Fortran IF statements where the result of either branch is the same 

• Unrolling complicated Fortran DO loops to improve vectorization 

• Use of the Fortran compiler directive CDIR$ IVDEP when no dependencies preventing vector^ 
zation exist 

These modifications increase vectorization and therefore reduce execution time. Only the order of com- 
putations within a loop is changed; the modified versions produce the same answers as the original ver- 
sions unless the problem is sensitive to small changes in the data. 

The following summary provides a list of the routines giving the name, matrix or decomposition, and 
the purpose for each routine. 



Name Matrix or Decomposition Purpose 

CG Complex general Find eigenvalues and eigenvectors 

CH Complex Hermitian 

RG Real general 

RGG Real general 

generalize (Ax = %Bx) 
RS Real symmetric 

RSB Real symmetric band 

RSG Real symmetric 

generalize {Ax = Xflx) 

RSGAB Real symmetric 

generalize (ABx =hc) 
RSGBA Real symmetric 

generalize (BAx - he) 
RSP Real symmetric packed 



SR-0113 



4-65 



D 



EISPACK(3SCI) 



EISPACK(3SCI) 



Name 

RST 

RT 

BALANC 

CBAL 

ELMHES 
ORTHES 
COMHES 
CORTH 

ELTRAN 
ORTRAN 



Matrix or Decomposition 

Real symmetric 
tridiagonal 
Special real 
tridiagonal 

Real general 

Complex general 

Real general 

Complex general 

Real general 



Purpose 



Balance matrix and isolate 
eigenvalues whenever possible 



Reduce matrix to upper Hessenberg 
form 



Accumulate transformations used 
in the reduction to upper 
Hessenberg form done by ELMHES, 
ORTHES 



BALBAK Real general 

ELMBAK 

ORTBAK 



COMBAK Complex general 

CORTB 

CBABK2 

REBAK 

REBAKB 



Form eigenvectors by back 
transforming those of the 
corresponding matrices 
determined by BALANC, ELMHES, 
ORTHES, COMMES, CORTH, and CBAL 



TRED1 
TRED2 
TRED3 

TRBAK 
TRBAK3 



Real symmetric 



Real symmetric 



IMTQLV Symmetric tridiagonal 

IMTQL1 

IMTQL2 

RATQR Symmetric tridiagonal 



TQLRAT Symmetric tridiagonal 



Reduce to symmetric tridiagonal 



Form eigenvectors by back 
transforming those of the 
corresponding matrices determined 
by TREDt or TRED3 

Find eigenvalues and/or 
eigenvectors by implicit QL 
method 

Find the smallest or largest 
eigenvalues by rational QR 
method with Newton corrections 

Find the eigenvalues by rational 
QL method 
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Name 



Matrix or Decomposition 



Purpose 



TQL1 
TQL2 



BISECT 
RIDIB 
TSTURM 
TINVIT 



Symmetric tridiagonal 



Find the eigenvalues and/or 
eigenvectors by the rational QL 
or QL method 

Find eigenvalues and/or 
eigenvectors that lie in a 
specified interval using 
bisection and/or inverse iteration 



FIGI 
FIGI2 



Nonsymmetric 
tridiagonal 



BAKVEC Nonsymmetric 



HQR 
HQR2 
COMQR 
COMQR2 

INVIT 

CINVIT 



BQR 



SVD 



Real upper Hessenberg 

Complex upper 
Hessenberg 

Upper Hessenberg 

Complex upper 
Hessenberg 



BANDR Real symmetric banded 



BANDV Real symmetric banded 



Real symmetric banded 



MINFIT Real rectangular 



Real rectangular 



Reduce to symmetric tridiagonal 
with the same eigenvalues 

Form eigenvectors by back 
transforming corresponding 
matrix determined by FIGI 

Find eigenvalues and/or 
eigenvectors by QR method 



Find eigenvectors corresponding 
to specified eigenvalues 



Reduce to a symmetric 
tridiagonal matrix 

Find those eigenvectors 
corresponding to specified 
eigenvalues using inverse iteration 

Find eigenvalues using QR 
algorithm with shifts of origin 

Determine the singular value 
decomposition A - USV T , forming 
U T B rather than U. 

Householder bidiagonalization and a variant 
of the QR algorithm are used. 

Determine the singular value 
decomposition A = USV T . 
Householder bidiagonalization 
and a variant of the QR algorithm are used. 
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Name 


Matrix or Decomposition 


Purpose 


HTRIBK 
HTRIB3 
HTRIDI 
HTRID3 


Complex Hermitian 


All eigenvalues and eigenvectors 


QZHES 
QZIT 
QZVAL 
QZVEC 


Real generalized 
eigenproblem (Ax - AJfcc) 


All eigenvalues and eigenvectors 


COMLR 

COMLR2 

REDUC 

REDUC2 


Complex general 

Real symmetric 
(Ax = XBx) 
Real symmetric 
(ABx = XBx 
or BAx = XBx) 


Reduce matrix to upper Hessenberg 

Transform generalized 
symmetric eigenproblems to 
standard symmetric eigenproblems 



IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

FILTERG - Computes a correlation of two vectors 

SYNOPSIS 

CALL FILTER G(a t m>d t n,o) 

DESCRIPTION 



a Vector of filter coefficients (input) 

m Number of filter coefficients (input) 

d Data vector (input) 

n Number of data points (input) 

o Resulting vector (output) 



FILTERG computes a correlation of two vectors. 
Given 

fa) 1=1, m Filter coefficients 

(dj) j=l 9 n Data 

FILTERG computes the following: 

m 

°i = X Oj di+j-i 1=1 n-m+1 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

FILTERS - Computes a correlation of two vectors (symmetric coefficient) 

SYNOPSIS 

CALL FJLTERS(a,m,d t n,r) 

DESCRIPTION 

a Symmetric filter coefficient vector (input) 

m m is formally the length of vector a, but because a is symmetric 

(a< = flm-i+i i - - ■* tf*X only ((m+1) div 2) elements of a are ever referenced (input) 
d Data vector (input) 

n Number of data points (input) 

r Resulting vector (output) 

FILTERS computes the same correlation as FTLTERG except that it assumes the filter coefficient vector 
is symmetric. 

Given 

fe) /=1, ..... fm/2l 
(dj) j=l> >n 

( \ml2] = y for w even, and ^ for m odd. This is called the ceiling function.) 
FILTERS computes the following when m is an odd number: 

(m-l)f2 

FILTERS computes the following when m is an even number: 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

FILTERG(3SCI) 
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NAME 

FOLR, FOLRP - Solves first-order linear recurrences 

SYNOPSIS 

CALL FOLRin.aMcaAincb) 
CALL FOURP(n,a,inca,b,incb) 

DESCRIPTION 



n Length of linear recuiTence (input) 

a Vector of length at least l+(n-l)*\inca\ used for recurrence (the first element of a in the 

recurrence is arbitrary) (input) 

inca Increment between recurrence elements of the vector operand a (input) 

b Vector of length at least l+(n-l)*\incb\ used as operand and for the result of the linear 

recurrence (input/output) 

inch Increment between recurrence elements of vector b (input) 



FOLR solves first-order linear recurrences as follows: 
Equation 1: 
b x = b x 

bi = bi-bi _ i * a t for i = 2, 3 . . . , n 

The Fortran equivalent of equation 1 is as follows: 

B(l)-B(l) 
DO 10 I = 2 t N 

B(I)=B(I)-B(I-1)*A(I) 
10 CONTINUE 

FOLRP solves first-order linear recuirences as follows: 
Equation 2: 

=b i +a i b i _ 1 for i = 2, 3 . . . , n 

The Fortran equivalent of equation 2 is as follows: 

B(1)=B(1) 
DO 10 I = 2, N 

B(I)=B(I)+A(I)*B(M) 
10 CONTINUE 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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CAUTIONS 

Do not specify inca or inch as zero; doing so yields unpredictable results. 
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NAME 

F0LR2, F0LR2P - Solves first-order linear recurrences without overwriting operand vector 

SYNOPSIS 

CALL FOLR2(n,a f inca t b,incb,c t incc) 
CALL VO\Jl2?{n t a 9 inca t b t incb t c 9 incc) 

DESCRIPTION 



n Length of linear recurrence (input) 

a Vector of length at least l+(n-l)*\inca\ used for recurrence (the first element of a in 

recurrence is arbitrary) (input) 

inca Inciement between recurrence elements of vector a (input) 

b Vector of length at least l+(/i-l)*|ind>| used as operand of linear recurrence (input) 

inch Increment between recurrence elements of vector b (input) 

c Vector of length at least l+(/i-l)*|wcc| to contain resulting vector of linear recurrence 

(output) 

incc Increment between recurrence elements of vector c (input) 



FOLR2 solves first-order linear recurrences as follows: 

Equation 1: 

c 1 = b l 

Ci = bi-ai * Ci_ x for i = 2,3,».»n 

The Fortran equivalent of equation 1 follows: 
(given for case inca = incb = incc =1) 

C(1)=B(1) 
DO 10 I=2JSf 

C(I)=B(I)-Aa)*C(I-l) 
10 CONTINUE 



FOLR2P solves first-order linear recurrences as follows: 

Equation 2: 

c l = b x 

Ci = bi+ai * for i = 2,3 
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The Fortran equivalent of equation 2 follows: 
(given for case inca = inch = incc - 1) 

C(1)=B(1) 
DO 10 I=2,N 

C(I)=B(I)+A(I)*C(I-1) 
10 CONTINUE 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
CAUTIONS 

Do not specify inca, inch, or incc as 0; doing so yields unpredictable results. 

SEE ALSO 

FOLR(3SCI) 
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NAME 

FOLRC - Solves first-order linear recurrence with constant coefficient 

SYNOPSIS 

CALL VOLRC(njc,incx,c4ncc,coef) 

DESCRIPTION 



n Length of linear recurrence (input) 

x Vector operand of length at least l+(n-l)*|jnce| (input/output) 

incx Increment between recurrence elements of vector x (input) 

c Vector operand of length at least l+(n-l)*\incc\ (input) 

incc Increment between recurrence elements of vector c (input) 

coef Coefficient used for recurrence (input) 



FOLRC solves a linear recurrence as in the Fortran equivalent below: 

1=1 
J=l 

IF (INCX XT. 0) THEN 
I = 1-(N-1)*INCX 

ENDIF 

IF (INCC. LT. 0) THEN 
J = 1-(N-1)*INCC 

ENDIF 
X(I) = C(J) 
DO 10 K=l, N 

X(I+INCX) = COEF*X(I) + C(J+INCC) 

J = J + INCC 

1 = 1 + INCX 
10 CONTINUE 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

CAUTIONS 

Do not specify incx or incc as zero; doing so yields unpredictable results. 
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NAME 

FOLRN - Solves for the last term of first-order linear recurrence using Homer's method 

SYNOPSIS 

result = FOLKN(n r a t inca,b t incb) 

DESCRIPTION 

n Length of the linear recurrence (input) 

a Vector of length at least l+(/t-l)*|mca[ used for recurrence {the first element of a in 

recurrence is arbitrary) (input) 

inca Increment between recurrence elements of the vector operand a (input) 

b Vector of length at least l+(n-l)*\incb\ used as operand for recurrence (input) 

incb Increment between recurrence elements of the vector b (input) 

FOLRN solves for r n of 
r\ = b x 

r g =bi -a,^ i = 2,3 n 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

CAUTIONS 

Do not specify incb as 0; doing so yields unpredictable results. 
EXAMPLE 

FOLRN allows for efficient evaluation of polynomials using Horner's method as follows: 
Let /;(*) = X bi x*~* 

i =0 

then p(a) = (».((6q* + b{) x + b£ x +...b H ) by Horner's rule. 

The Fortran equivalent is as follows: 

PA = B(0) 
DO10I = l,N 

PA = PA * X + B(I) 
10 CONTINUE 

or 

PA=FOLRN(N+1,-X,03(0)a) 

SEE ALSO 

FOLR(3SCI) 
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NAME 



FOLRNP - Solves for last term of a first-order linear recurrence 



SYNOPSIS 



result - FOLKNP(n,a,inca,b,incb) 



DESCRIPTION 



incb 



inca 



a 



n 



Length of the linear recurrence (input) 

Vector of length at least l+(n-l)*\inca\ used for recurrence (input) 
Increment between recurrence elements of the vector operand a (input) 
Vector of length at least l+(n-l)*\incb\ used for recurrence (input) 
Increment between recurrence elements of the vector operand b (input) 



FOLRNP solves a linear recurrence as in the following Fortran equivalent: 

K=l 
J=l 

IF (INCX .LT. 0) THEN 

K = 1 - (N-l) * INCX 

ENDIF 

IF (INCC XT. 0) THEN 

J = 1 - (N-l) * INCC 

ENDIF 

RESULT = B(J) 
DO 10 I = 2, N 

RESULT = A(K+INCA) * RESULT + B(J+INCB) 

J = J + INCB 

K = K + INCA 
10 CONTINUE 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

CAUTIONS 

Do not specify inca or incb as 0; doing so yields unpredictable results. 
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NAME 

GATHER - Gathers a vector from a source vector 

SYNOPSIS 

CALL GATHER(n,a,b>index) 

DESCRIPTION 

n Number of elements in vectors a and index (not in b) (input) 

a Resulting vector (output) 

b Source vector (input) 

index Vector of indices (input) 

GATHER is defined in the following way: 

a,- - bj. where i = 1, . . . f n 

In Fortran: 

DO 100 i=ijsr 

A(I)=B(INDEX(I)) 
100 CONTINUE 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

LINPACK - Single-precision real and complex UNPACK routines 



DESCRIPTION 

LINPACK is a package of Fortran routines that solve systems of linear equations and compute the QR, 
Cholesky, and singular value decompositions. The original Fortran programs are documented in the 
UNPACK User's Guide by J. J, Dongarra, C. B. Moler, J. R. Bunch, and G. W. Stewart, published by 
the Society for Industrial and Applied Mathematics (SIAM), Philadelphia, 1979, Library of Congress 
catalog card number 78-78206. This guide is available through Cray Research as publicaton S 1-01 13. 

Each single-precision scientific library version of the LINPACK routines has the same name, algorithm, 
and calling sequence as the original version. Optimization of each routine includes the following: 

• Replacement of calls to the BLAS routines SSCAL, SCOPY, SSWAP, SAXPY, and SROT with 
in-line Fortran code vectorized by the Cray Fortran compilers 

• Removal of Fortran IF statements where the result of either branch is the same 

• Replacement of SDOT to solve triangular systems of linear equations in SGESL, SPOFA, 
SPOSL, STRSL, and SCHDD with more vectorizable code 



These optimizations affect only the execution order of floating-point operations in DO loops. See the 
UNPACK User's Guide for further descriptions. The complex routines have been added without much 
optimization. 

The following summary provides a list of the routines, giving the name, matrix or decomposition, and 
the purpose for each routine. 



Name 

SGECO 
SGEFA 
SGESL 
SGEDI 

CGECO 
CGEFA 
CGESL 
CGEDI 

SGBCO 
SGBFA 
SGBSL 
SGBDI 

CGBCO 
CGBFA 
CGBSL 
CGBDI 



Matrix or Decomposition 
Real general 



Complex general 



Real general banded 



Complex general banded 



Purpose 

Factor and estimate condition 

Factor 

Solve 

Compute determinant and inverse 

Factor and estimate condition 

Factor 

Solve 

Compute determinant and inverse 

Factor and estimate condition 

Factor 

Solve 

Compute determinant 

Factor and estimate condition 

Factor 

Solve 

Compute determinant 
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Name Matrix or Decomposition Purpose 

SPOCO Real positive definite Factor and estimate condition 

SPOFA Factor 

SPOSL Solve 

SPODI Compute determinant and inverse 

CPOCO Complex positive Factor and estimate condition 

CPOFA definite Factor 

CPOSL Solve 

CPODI Compute determinant and inverse 

SPPCO Real positive definite Factor and estimate condition 

SPPFA packed Factor 

SPPSL Solve 

SPPDI Compute determinant and inverse 

CPPCO Complex positive Factor and estimate condition 

CPPFA definite packed Factor 

CPPSL Solve 

CPPDI Compute determinant and inverse 

SPBCO Real positive definite Factor and estimate condition 

SPBFA banded Factor 

SPBSL Solve 

SPBDI Compute determinant 

CPBCO Complex positive Factor and estimate condition 

CPBFA definite banded Factor 

CPBSL Solve 

CPBDI Compute determinant 

SSICO Symmetric indefinite Factor and estimate condition 

SSIFA Factor 

SSISL Solve 

SSIDI Compute inertia, determinant, 

and inverse 

CSICO Complex symmetric Factor and estimate condition 

CSIFA Factor 

CSISL Solve 

CSIDI Compute determinant and inverse 

CHICO Hermitian indefinite Factor and estimate condition 

CHIFA Factor 

CHISL Solve 

CHIDI Compute inertia, determinant, 

and inverse 

SSPCO Symmetric indefinite Factor and estimate condition 

SSPFA packed Factor 

SSPSL Solve 

SSPDI Compute inertia, determinant, 

and inverse 
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Name 



Matrix or Decomposition 



Purpose 



CSPCO 
CSPFA 
CSPSL 
CSPDI 



CHPCO 
CHPFA 
CHPSL 
CHPDI 



STRCO 

STRSL 

STRDI 

CTRCO 
CTRSL 
CTRDI 

SGTSL 

CGTSL 

SPTSL 

CPTSL 

SCHDC 
SCHDD 
SCHUD 

SCHEX 

CCHDC 
CCHDD 
CCHUD 
CCHEX 

SQRDC 
SQRSL 

CQRDC 
CQRSL 

SSVDC 

CSVDC 



Complex symmetric 
indefinite packed 



Hermitian indefinite 
packed 



Real triangular 

Complex triangular 

Real tridiagonal 

Complex tridiagonal 

Real positive definite 
tridiagonal 

Complex 

Real Cholesky 
decomposition 



Complex Cholesky 
decomposition 



Real 

Complex 

Real 
Complex 



Factor and estimate condition 

Factor 

Solve 

Compute inertia* determinant, 
and inverse 

Factor and estimate condition 

Factor 

Solve 

Compute inertia, determinant, 
and inverse 

Factor and estimate condition 
Solve 

Compute determinant and inverse 

Factor and estimate condition 
Solve 

Compute determinant and inverse 

Solve 

Solve 

Solve 



Solve 

Decompose 
Downdate 
Update 
Exchange 

Decompose 
Downdate 
Update 
Exchange 

Orthogonal factorization 
Solve 

Orthogonal factorization 
Solve 

Singular value decomposition 



IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

MINV - Solves systems of linear equations by inverting a square matrix 
SYNOPSIS 

CALL MSNV(ab,n,ldab,scratch,det,tot t m,mode) 
DESCRIPTION 

ab Array containing the augmented matrix A:B. A is the square matrix to be inverted and B is 

the matrix whose columns are the sources for the systems of linear equations to be solved, 
(input) 

A:B is overwritten by the solutions and (optionally) by the inverse of A. (output) 

n Older of matrix A; that is, A is an n-by-n matrix, (input) 

Idab Leading dimension of array ab. (input) 

scratch Array of at least 2*n elements used by MINV as a work space. 

det Determinant of A, computed as the product of pivot elements, (output) 

tol Lower limit for the determinant's partial products. Matrix A is declared singular once the 

partial product of pivot elements is less than or equal in magnitude to this parameter, which 
should be positive, (input) 

m Number of columns in B. This number may be 0. (input) 

mode Parameter specifying whether or not the inverse of A is required. 
In ab y A is overwritten by its inverse only if modeoO. (input) 

MINV can be used to solve systems of linear equations, compute the inverse of a square matrix, or 
compute the determinant of the matrix. 

If m>0, MINV solves 

A*X = B 

for the n-by-m matrix X, replacing B by X (that is, the solution overwrites B). 
Thus, MINV solves m systems of linear equations: 

A*X(: j) = B(: j) , j = 1, 2, 3 m , 

where X(: j) and B(: j) denote the j-th columns of X and B, respectively. 

If modeoO^ MINV replaces A by the inverse of A. 

If mode=0, A is overwritten, but not by the inverse of A. 

The effect of mode is independent of the value of m. 

Regardless of the values of m and mode, MINV computes the determinant of A, subject to the restric- 
tion imposed by tol (see CAUTIONS). 
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The following table summarizes the effect of different combinations of parameter values: 



Parameter values 



Results returned by MINV 



m=0 , mode=0 
/n=0, modeoO 
m>0 f mode=Q 
rroO , modeoO 



det(A) 

det(A) y A**(-l) 

det(A) 9 X=(A**(-1))*B 

det(A). A**(-l), X=(A**(-1))*B 



A**(-l) denotes the inverse of A. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

MINV solves linear equations using a partial pivot search (one unused row) and Gauss-Jordan reduction. 



1. W, P. Petersen, "Partial Pivoting Linear Equation Solver (MINV)", Cray Computer Systems Techni- 
cal Note SN-0215 (1980). 

2. D. E* Knuth, The Art of Computer Programming, Volume 1 (Fundamental Algorithms), (Addison- 
Wesley, Reading, MA, 1973); pp. 301-302. 



At each reduction step, MINV computes the partial product of pivot elements. MINV aborts computa- 
tion if this product's magnitude is less than or equal to tot. Therefore, if the value returned in det is 
less or equal in magnitude to the value input as tol y then MINV did not invert A or solve for X 
(although A:B may have been overwritten); in this case, the value returned in det may not be the deter- 
minant of A. 

EXAMPLES 

Example 1. 

The following program computes only the determinant of a square matrix, overwriting the matrix in the 
process. 

PROGRAM MINV1 
DIMENSION A(4,4), SCRATCH(8) 
DATAA/5.,7,,6.,5.,7.,10.,8.,7.,6.,8.,10.,9,,5.,7.,9.,107 
CALL MINV(A,4,4,SCRATCH,DET,1E-12,0,0) 
WRITE^^A^.^)') 'Determinant = \ DET 
END 

Output: 

Determinant = 1.000000000002 
(The matrix is unimodular.) 
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Example 2. 

This program computes the inverse of the matrix whose determinant was computed in Example 1. 



PROGRAM MINV2 

DIMENSION A(4,4), AINV(4,4), SCRATCH(8), E(4,4), P(4,4) 
DATA A/5.,7.,6.,5.,7.,10.,8.,7.,6.,8.,10.,9.,5.,7.,9.,10./ 
& E/l.,4*0.,l.,4*0.,l.,4*0.,l./ 

c copy A into AENV 
AINV = A 

CALL MINV(AINV,4,4,SCRATCH,DET, IE- 12,0,1) 
WRITE(6,902) ((A(U)J=1,4), (AINVaJ)J=l,4), 1=1,4) 
c compare A* AINV to E 

CALL MXM(A,4,AINV,4,P,4) 
WRITE(6,903) ((P(IJ)-E(IJ)J=1,4),I=1,4) 

902 FORMAT(4(/4F5.0,9X,4F5.0)) 

903 FORMAT(4(/1X,4(E10.4,5X))) 
END 



Output: 



5. 


7. 


6. 


5 


7. 


10. 


8. 


7 


6. 


8. 


10. 


9 


5. 


7. 


9. 


10 



68. -41. -17. 10. 

-41. 25. 10. -6. 

-17. 10. 5. -3. 

10. -6. -3. 2. 



0.6821E-12 
0.4093E-11 
0.2274E-11 
0.2274E-11 



0.9095E-12 
-.6821E-12 
-.2274E-12 
0.0000E+00 



-.2274E-12 
-.5684E-12 
-.341 IE- 12 
-.4547E-12 



0.5684E-13 
0.7958E-12 
0.4547E-12 
0.2274E-12 



Though not printed, the determinant of the input matrix is available in the variable del after the call to 
MINV. 
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Example 3. 

In the following program, MINV solves 
A*X = B 

for the two-column matrix X, where A is the same 4-by-4 matrix used for input in the previous exam- 
ples. 

PROGRAM MINV3 

DIMENSION AB(4,6), SCRATCH(8) 

DATA 

& AB/5.,7.,6.,5.,7.,10.,8.,7.,6.,8.,10.,9.,5.,7.,9.,10., 
c first column of B 

& 0.,1.,2.,3., 
c second column of B 

& \.XXXI 
WRITE(6,904) 'input matrix A:B\ ((AB(IJ),J=1,6), 1=1,4) 
CALL MINV(AB,4,4,SCRATCHJ>ET,1E-10,2,0) 
WRITE(6,904) 'output matrix', ((AB(IJ)J=1,6), 1=1,4) 
904 FORMAT(/A/4(/6F5.0)) 
END 

The solution matrix is stored in the last two columns of AB, as shown by the program's output 



input matrix A:B 



5. 7. 


6. 


5. 


0. 


1. 


7. 10. 


8. 


7. 


1. 


2. 


6. 8. 


10. 


9. 


2. 


1 . 


5. 7. 


9. 


10. 


3. 


2. 


output matrix 










10. 68. 


-41. 


-17. 


-45. 


-11. 


-6. -41. 


25. 


10. 


27. 


7. 


-3. -17. 


10. 


5. 


11. 


2. 


2. 10. 


-6. 


-3. 


-6. 


-1. 



The first four columns of ab, which were occupied by A on input, have been overwritten. 

SEE ALSO 

SGEFA in LINPACK(3SCI) 
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NAME 

MXM - Computes matrix-times-matrix product (unit increments) 

SYNOPSIS 

CALL MXM(a,nraJbjica,cjicb) 

DESCRIPTION 



a Matrix A, the first factor (input) 

nra Number of rows in A (input) 

b Matrix B, the second factor (input) 

nca Number of columns in A (input) 

c Matrix C, the product A*B (output) 

neb Number of columns in B (input) 



MXM computes the nra-by-ncb matrix product C=A*B of the nra-by-nca matrix A and the nca-by-ncb 
matrix B. 

The following Fortran subroutine is equivalent to MXM: 

SUBROUTINE VTXMF(A,NRA,B ) NCA,C,NCB) 
DIMENSION A(NRA,NCA), B(NCA,NCB), C(NRA,NCB) 
c initialize product 
DO 120 K=l, NCB 
DO 110 1=1, NRA 
C(I,K)=0 
110 CONTINUE 
120 CONTINUE 
c multiply matrices A and B 
DO 230 K=l, NCB 
DO 220 J=l, NCA 
DO 210 1«l, NRA 

C(IJC)=Ca,K)+A(IJ)*B(J > K) 
210 CONTINUE 
220 CONTINUE 
230 CONTINUE 
RETURN 
END 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

MXM is restricted to multiplying matrices whose elements are stored by columns in successive memory 
locations. MXMA is a general subroutine for multiplying matrices that can be used to multiply matrices 
that do not satisfy the requirements of MXM. 

MXV is similar to MXM, but is specialized to the case of a matrix times a vector. 
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CAUTIONS 

To be computed correctly, the product must not overwrite either factor. Thus, for example, 

CALL MXM(A J NRA,B,NCA,A 1 NCA) 
will not (in general) assign the product A*B to A. 

EXAMPLE 

The following program multiplies a 4-by-4 matrix and a 4-by-3 matrix. 

PROGRAM MXM1 

DIMENSION A(4,4), B(4,3), C(4,3) 

DATAA/3.,2.,7.,1.,6.,3.,1.,6.,4.,6.,4.,2.,1.,3.,7.,5./ 
& B/-5.,6.,4.,3.,2.,l.,-3.,6.,l.,5.,-4.,4y 

CALL MXM(A,4,B,4,C,3) 

WRITE(6,901) ((A(I,J),J=1,4), (B(IJ),J=1,3), 
& (C(Uy=l,3), 1=1,4) 

901 FORMAT(4(/4F4.0,4X,3F4.0,9X,3F4.0)) 

END 



Output: 



3. 


6. 


4. 


1. 


-5. 


2. 


1. 


40. 


6. 


21. 


2. 


3. 


6. 


3. 


6. 


1. 


5. 


41. 


7. 


5. 


7. 


1. 


4. 


7. 


4. 


-3. 


-4. 


8. 


45. 


24. 


1. 


6. 


2. 


5. 


3. 


6. 


4. 


54. 


32. 


43. 



SEE ALSO 

MXMA(3SCI), MXV(3SCI) 
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NAME 

MXMA - Computes matrix-times-matrix product (arbitrary increments) 
SYNOPSIS 

CALL MXMk{sa t iaciar t sb,ibcibr % sc^cc t icr t nrp t m t ncp) 
DESCRIPTION 

sa Array containing matrix A, the first operand (input) 

iac Increment in sa between adjacent elements in a column of A (input) 

iar Increment in sa between adjacent elements in a row of A (input) 

sb Array containing matrix B, the second operand (input) 

ibc Increment in sb between adjacent elements in a column of B (input) 

ibr Increment in sb between adjacent elements in a row of B (input) 

sc Array receiving C, the product A*B (output) 

ice Increment in sc between adjacent elements in a column of C (input) 

icr Increment in sc between adjacent elements in a row of C (input) 

nrp Number of rows in C (that is, the number of rows in A) (input) 

m Middle dimension: number of columns in A and number of rows in B (input) 

ncp Number of columns in the product (that is, the number of columns in the second operand B) 
(input) 

Let A denote the nrp-by-m matrix defined by iac and iar in array sa; and let B denote the m-by-ncp 
matrix defined by ibc and ibr in sb. 

MXMA returns the nrp-by-ncp matrix product C=A*B in elements of C specified by ice and icr. 
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The following Fortran subroutine is equivalent to MXMA: 
SUBROUTINE 

& MXMAF(SAJAC4AR,SB,IBC,IBR,SCJCCJ[CRJJRP t M^CP) 
DIMENSION SA(1), SB(1), SC(1) 
c INITIALIZE PRODUCT 
DO 120 K = 1, NCP 
DO 1101= l.NRP 
SC( 1 + a-l)*ICC + (K-1)*ICR ) = 0. 
c ( C(IJC) := 0. ) 

110 CONTINUE 
120 CONTINUE 

c MULTIPLY MATRICES FROM SA AND SB 
DO230K= 1,NCP 
DO 220 J = 1, M 
DO 2101= l.NRP 

SC( 1 + (I-1)*ICC + (K-1)*ICR ) 
& = SC( 1 + (I-1)*ICC + (K-l)*ICR ) 

& + SA( 1 + (M)*IAC + (M)*IAR ) 

& * SB( 1 + (M)*IBC + (K-1)*IBR ) 

c ( C(I,K) := C(I,K) + A(LJ)*B(J,K) ) 

210 CONTINUE 
220 CONTINUE 
230 CONTINUE 
RETURN 
END 

This subroutine shows how nrp, m, ncp, and the six increments define the locations of the operands and 
result in the arrays sa, sb, and sc. 

Interchanging the arguments specifying column and row increments for one of the matrices involved in 
the computation (A, B, or C) is equivalent to replacing that matrix by its transpose. Consider the first 
operand: in the subroutine MXMAF (in the previous example), interchanging iac and iar replaces A(IJ) 
with A(JJ). 

Commonly, sa, sb, and sc are two-dimensional arrays. If they are defined to have leading dimensions 
Idsa, Idsb, and Idsc as follows: 

DIMENSION SA(LDSA,NCP), SB(LDSB,NCP), SC(LDSQNCP) 

then 

CALLMXMA(SA,IAClDSA,SB,IBCXDSB,SCJCCXDSC,NRPJvrCPJJCP) 
multiplies a submatrix of sa and a submatrix of sb, storing the product in a submatrix of sc, while 

CALL MXMA(SAJAC,LDSA,SBJLDSBJBC,SC,ICC1DSC,NRPJMCPJ*:P) 
computes the product of A and the transpose of B. 

NOTE 

MXMA is a general subroutine for multiplying matrices. It can be used to compute a product of 
matrices where one or more of the operands or the product must be transposed. MXMA can be used to 
multiply any matrices whose elements are not stored by columns in successive memory locations, pro- 
vided only that the elements of rows and columns are spaced by increments constant for each matrix. 
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MXVA is a similarly general subroutine that computes the product of a matrix and a vector. 

The product of matrices whose elements are stored by columns in successive memory locations can be 
computed slightly faster using MXM. 

The following subroutine calls are equivalent: 

CALL MXMA(SA,l,NRP f SBa,M,SC4,NCT ) NRP > M»NCP) 

CALL MXM(SA,NRP,SBJ^»SC^CP) 
(The product elements computed by MXM are also stored by columns in successive memory locations). 
CAUTION 

To be computed correctly, the product must not overwrite either operand. Thus, if alpha is a one- 
dimensional array, 

CALL MXMA(ALPHA,3,9,BETA,U,ALPHA(2),1 > 3 ) 3,2,2) 
correctly computes the product of the matrices defined in alpha and beta, whereas 

CALL MXMA(ALPHA,3,9,BETA,1,2ALPHA,1,3, 3,2,2) 

does not (in general). 

EXAMPLES 

Example 1. 

Suppose sa, sb, and sc are dimensioned as follows: 

REAL SA(3,3), SB(4,3), SC(4,3) 
then CALL MXMA(SA,1,3,SB,4,1,SC,3,8,2,3,2) 

multiplies a 2-by-3 matrix operand A from sa times a 3-by-2 matrix operand B from sb, storing the 2- 
by-2 matrix product C in sc. 

Elements of the matrices A, B, and C are identified with elements of the arguments sa, $b t and sc % 
respectively, as follows: 



memory 


operand 


memory 


operand 


memory 


product 


M(U) — 


A(l,l) 


*6(1,1) == 


B(l,l) 


5C(1,1) = 


C(l,l) 


50(2,1) = 


A(2,l) 


56(2,1) = 


B(l,2) 


5C(2,1) 




*»(3,1) 




*6(3,1) 




5C(3,1) 




sa{\, 2) = 


A(l,2) 


*6(4,1) 




5 C (4,1) = 


C(2,l) 




A(2,2) 


56(1,2) = 


B(2,l) 


5C(1,2) 




m(32) 




sb(2,2) = 


B(2,2) 


rc(2,2) 




50(1,3) = 


A(I,3) 


56(3,2) 








so<2,3) = 


A(2,3) 


56(4,2) 




sc(4,2) 




M(3,3) 




56(1,3) = 


B(3,l) 


5C(1,3) = 


C(l,2) 






56(2,3) == 


B(3,2) 


5c(2,3) 








56(3,3) 




jc(3,3) 








56(4,3) 




5C(4,3) = 


C(2,2) 
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The columns labeled "memory" list all the elements of the arrays sa, sb, and sc in the order of their 
storage addresses; the columns labeled "operand" show the role of these elements in the computation. 
Note that B(i j) = B(j4): in this example, B is a submatrix of the transpose of sb. 

Example 2. MXMA accepts non-positive increments. 
Consider the following program: 

PROGRAM MXMA2 

DIMENSION Al(33), A2(3,3), B(3,3), C(3,2) 

DATA Al/l.,2.,99..3.,4.,99..99.,99.,99y 
& A2/4.,3.,99.,2.,l.,99.,99.,99.,99./ 
& B/0.,42.,1.,1.,42.,2.,3.,42.,5./ 

CALL MXMA(al,1.3,b,23,c3,l,2,2,3) 

WRITE(6,901) ((Aiaj)J=l,3), 
& (B(IJ)J=1,3), (CaJ)J=l,2), 1=1,3) 

CALLMXMA(A2(2^),-1,-3,B^3.C,3,U,2,3) 

WRITE(6,901) ((A2(IJ)J=1,3), 
& (B(U),J=1,3), (CaJ)J=l,2), 1=1,3) 

901 FORMAT(3(/3F4.0,9X,3F4.0,9X,2F4.0)) 

END 

which produces the following output: 

1. 3. 99. 0. 1. 3. 3. 4. 

2. 4. 99. 42. 42. 42. 7. 10. 
99. 99. 99. 1. 2. 5. 18. 26. 

4. 2. 99. 0. 1. 3. 3. 4. 

3. 1. 99. 42. 42. 42. 7. 10. 
99. 99. 99. 1. 2. 5. 18. 26. 

This demonstrates that both calls to MXMA define the same first operand. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

MXM(3SCI), MXVA(3SCI) 
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NAME 

MXV - Computes matrix-times-vector product (unit increments) 

SYNOPSIS 

CALL MXV(a,nra,b,nca,c) 

DESCRIPTION 



a Matrix factor (input) 

nra Number of rows in the matrix (input) 

b Vector factor (input) 

nca Number of columns in the matrix (input) 

c Vector product (output) 



MXV computes the nra- vector product G=A*B of the nra-by-nca matrix A and the /ica-vector B. 
The following Fortran subroutine is equivalent to MXV: 

SUBROUTINE MXVF(A,NRA,B.NCA,C) 

DIMENSION A(NRA,NCA) t B(NCA) f C(NRA) 
c initialize product 

DO 1001 = 1, NRA 
C(I) = 0. 
100 CONTINUE 

c multiply matrix A and vector B 

DO 220 J = 1, NCA 
DO 210 1 = 1, NRA 
C(I) = C(I)+A(U)*B(J) 
210 CONTINUE 
220 CONTINUE 
RETURN 
END 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

MXV is restricted to multiplying a vector occupying successive memory locations (in order) by a matrix 
whose elements are stored by columns in successive memory locations. MXVA is a general subroutine 
for multiplying a matrix and a vector, which can be used to multiply a vector by a matrix stored with 
arbitrary column and row increments. 
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EXAMPLES 

The following program multiplies a 3-by-4 matrix and a 4-element vector: 

PROGRAM MX VL 
DIMENSION A(3.4), B(4), C(3) 
DATAA/9.,4.,2.,3.,3..5..7.,l.,7.,4.,2.,2./B/l.,-2..-1..3./ 
CALL MXV(A.33,4,C) 

WRITE(6,901) ((A(I,J)J=1.4). B(I), C(I), 1=1.3). B(4) 
901 FORMAT(3(/4F4.0.T20.F4.0,T30,F4.0)/r20.F4.0) 
END 

Output: 



9. 


3. 


7. 


4. 


1. 


8. 


4. 


3. 


1. 


2. 


-2. 


3. 


2. 


5. 


7. 


2. 


-1. 


-9. 



3. 



CAUTIONS 

To be computed correctly, the product must not overwrite either factor. Thus, for example, 

CALL MXV(A,N,B,N,B) 

will not (in general) assign to B the product A*B. 

SEE ALSO 

MXVA(3SCI) 
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NAME 

MXVA - Computes matrix-times-vector product (arbitrary increments) 

SYNOPSIS 

CALL MX VA(sa> iac t iar,sb,ib>sc t ic,nra,nca) 

DESCRIPTION 



sa Array containing matrix A f the first operand (input) 

iac Increment in sa between adjacent elements in a column of A (input) 

iar Increment in sa between adjacent elements in a row of A (input) 

sb Array containing vector B, the second operand (input) 

ib Increment in sb between adjacent elements of B (input) 

sc Array receiving C, the product A*B (output) 

ic Increment in sc between adjacent elements of the product (input) 

nra Number of rows in A (input) 

nca Number of columns in A (input) 



Let A denote the nra-by-nca matrix defined by iac and iar in array sa; let B denote the nca-vector 
defined by ib in sb. MXVA returns the /ira-vector product C=A*B in elements of sc specified by ice 
and icr w 

The following Fortran subroutine is equivalent to MXVA: 

SUBROUTINE MXVAF (SAIAC 1 IAR t SB,IB t SCJC t NRA,NCA) 
DIMENSION SA(1), SB(1), SC(1) 
initialize product 
DO 1001= 1, NRA 
SC( 1 + (I-1)*IC ) = 0. 
( CO) := 0. ) 
CONTINUE 

multiply matrix from sa and vector from sb 
DO 220 J = 1, NCA 
DO 210 1 = 1, NRA 
SC( 1 + (I-D*IC ) 
& =SC(1+(I-D*IC) 
& + SA( 1 +• (M)*IAC + (J-1)*IAR ) 
& * SB( 1 +(J-1)*IB ) 

(C(i) C(i) + A(ij)*BG)) 
CONTINUE 
CONTINUE 
RETURN 
END 

This subroutine shows how iac, iar, ib, ic, nra, and nca define the locations of the operands and result 
in the arrays sa, sb, and sc. 

Interchanging the arguments specifying column and row increments for the matrix has the effect of 
replacing the matrix by its transpose. In subroutine MXVAF (previous example), interchanging iac and 
iar replaces A(/, j) by AQV /)• 



c 

100 
c 



c 

210 

220 
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Suppose sa is a two-dimensional array defined to have leading dimension Idsa as follows: 
DIMENSION SA(LDSA,NCA) 

Then 

CALL MXVA(SA,IAC t LDSA,SB,IB,SCJC,NCA f NCA) 
multiplies a submatrix A of sa times a vector from sb t storing the product in sc y while 

CALL MXVA(SA,LDSA,IAC,SB t IB»SC,IC t NCA t NCA) 
computes the product of the transpose of A times the same vector from sb. 

NOTES 

MXVA is a general subroutine for multiplying a matrix and a vector, and is operationally similar to 
MXMA. MXVA can be used to multiply a vector by any matrix whose elements are not stored by 
columns in successive memory locations, provided only that the elements of rows and columns are 
spaced by constant increments. The factor and product vector increments are independent and arbitrary. 

The product of a matrix whose elements are stored by columns in successive memory locations and a 
vector stored likewise can be computed somewhat faster using MXV. The following two subroutine 
calls have the same result: 

CALL MX VA(S A, 1 f NRA, SB , 1 , SC, 1 ^NRA, NC A) 
CALL MXV<SA,NRA,SB,NCA,SC) 

(The product elements computed by MXV are also stored in successive memory locations.) 
EXAMPLES 

Example L Suppose sa, sb> and sc are dimensioned as follows: 
REAL SA(3,3), SB(9), SC(8) 

Then 

CALL MXVA(5A t 13,SB t 4 v SC v 3,2.3) 

multiplies a 2-by-3 matrix operand A from sa times a 3-element vector operand B from sb, storing 

the 2-element vector product C in sc. Elements of the matrix A and the vectors B and C are identified 

with elements of the arguments sa, sb 9 and sc y respectively, as follows: 



memory operand memory operand memory product 



*a(l,l) 


== A<U) 


sb(i) == 


B(l) 


sc(l) 


== C(l) 


**(2,1) 


= A(2,1) 


sb(2) 




sc(2) 




sa(3,l) 




sb{3) 




sc(3) 




sa(l a) 


= A(l,2) 


sMA) 




sc(4) 


==C(2) 


sa(2,2) 


= A(2,2) 


sb(5) == 


B(2) 


sc(5) 




sa(3,2) 




sb® 




sc(6) 




sa(l,3) 


= A(l,3) 


sbO) 




scO) 




sa(2£) 


= A(2,3) 


sb(S) 




jc(8) 




.sa(3,3) 




sb(9) == 


B<3) 
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The columns labeled "memory" list all the elements of the arrays sa> sb 9 and sc in the order of their 
storage addresses; the columns labeled "operand" show the role of these elements in the computation. 

Example 2, In the following program, the first call to MXVA computes the product of the 3-by-5 
matrix A and the 5-element vector B; the second call computes the product of the 5-by-3 transpose of 
A and the 3-element vector (B(1),B(2),B(3)): 

PROGRAM MXVA2 

DIMENSION A(3,5) f B(5) f C(5) 

DATA A/l.,2.,-5.,-8.,-6.,3^8.,-7.,4,,1.,-5.,0.,5.,6.^6./ 
& B/6.,-1.,2.,8.,4./ 
& C/5*(y 

CALL MXVA(A t l t 33,UC,l,3,5) 

WRJTE(6,901) ((A(I,J)J=1,5), B(I), C(IX 1-1,3), 

& m\ cax 1=4,5) 

CALL MXVA(A3>134,C f 1,5,3) 
WRTTE(6 f 901) <(A(U),J=1,5X B(I), C(I>, 1=1,3), 
& (B(1X C(I)< 1=4,5) 

901 FORMAT(3(/5F4.0 ( T25 t F4.0,T35,F4.0) > 2(/r25,F4.0,T35 t F4.0)/) 
END 

The output of this program is as follows: 



1. 


-8. 


8. 


1. 


5. 


6. 


58. 


2. 


-6. 


-7. 


-5. 


6. 


-1. 


-12. 


-5. 


3. 


4. 


0. 


6. 


2. 


-1. 












8. 


0. 












4. 


0. 


1. 


-8. 


8. 


1. 


5. 


6. 


-6. 


2. 


-6. 


-7. 


-5. 


6. 


-1. 


-36. 


-5. 


3. 


4. 


0. 


6. 


2. 


63. 












8. 


11. 












4. 


36. 



Example 3. The following program multiplies a 2-by-3 matrix and a 3-element vector, storing the 
product's two elements in reverse order 

PROGRAM MXVA3 
DIMENSION A(3,2), B(3). C(3) 
DATA A/2.,9.,8.,4.,3.,7./B/4.,-4.,l./C/3*0./ 
CALL MXVA(A,3,l,B,l,C(3),-2,2,3) 
WRITE(6.901) ((A(I,J),J=1.2), B(I), C(I), 1=1.3) 
901 FORMAT(3(/2F4.0,4XJ J 4.0,9X.F4.0)) 
END 

Output: 

2. 4. 4. 11. 

9. 3. -4. 0. 

8. 7. 1. -20. 
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IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

CAUTIONS 

To be computed correctly, the product must not overwrite either operand. Thus, for example, 

CALL MX VA(S AJAC,IAR,SB , IB , SB JB .NRA.NCA) 
will not (in general) compute correctly the product of the matrix in sa and the vector in sb. 

SEE ALSO 

MXV(3SCI), MXMA(3SCI) 
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NAME 

OPFILT - Solves Weiner-Levinson linear equations 

SYNOPSIS 

CALL OPFlLT(m,aAc,r) 

DESCRIPTION 



m Order of the system of equations (input) 

a Resulting vector of m filter coefficients (output) 

b Information auto-correlation vector of length m (input) 

c Scratch vector of length 2m 

r Signal auto-correlation vector of length m (input) 



OPFILT computes the solution to the Weiner-Levinson system of linear equations Ta=b, where T is a 
Toeplitz matrix in which elements are described by the following: 

fy for \ | + l = k 

and k = 1, . . n 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

Although OPFILT solves this matrix equation faster than Gaussian elimination can, OPFILT does no 
pivoting; therefore, it is less numerically stable than Gaussian elimination unless the matrix T is posi- 
tive definite, or diagonally dominant. 

EXAMPLES 

The following system of linear equations can be solved with the call OPFILT (3,A,B,C,R). The vector 
C has a length of at least six. (The elements show how the numbers for R are obtained.) 



R(2)R(l)R(2) 
fe(3) *<?)*<!) J 



'a hi hi 

hi *22 *23 

hi hi hi 













I J 
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NAME 



RECPP - Solves a partial products problem 



SYNOPSIS 



CALL KECPF(njcjncx,c,incc) 



DESCRIPTION 



incc 



x 



c 



incx 



n 



Recurrence length (input) 

Vector of length at least l+(n-l)*|t'ncx| (input/output) 
Increment between recurrence elements in vector x (input) 
Vector of length at least l+(n-l)*|mcc| (input) 
Increment between recurrence elements in vector c (input) 



RECPP solves a partial products problem as in the following Fortran equivalent: 

1=1 
J=l 

IF (INCX XT. 0) THEN 
I = 1-(N-1)*INCX 

ENDIF 

IF (INCC. LT. 0) THEN 
J = 1-(N-1)*INCC 

ENDIF 
X(I) = C(J) 
DO 10 I=2,N 

X(I+INCX) = C(J+INCC)*X(I) 

J = J+INCC 

I = I+INCX 
10 CONTINUE 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 



RECPS - Solves a partial summation problem 



SYNOPSIS 



CALL RECPS(njc,incx,c,incc) 



DESCRIPTION 



tncc 



x 



n 



mcx 



c 



Recurrence length (input) 

Vector of length at least l+(n-l)*|i«cx| (input/output) 
Increment between recurrence elements in vector x (input) 
Vector of length at least l+(n-l)*|i«cc| (input) 
Increment between recurrence elements in vector c (input) 



RECPS solves a partial summation problem as in the following Fortran equivalent: 

1=1 
J=l 

IF (INCX .LT. 0) THEN 
I = 1-(N-1)*INCX 

ENDIF 

IF (INCC IX 0) THEN 
J = 1-(N-1)*INCC 

ENDIF 
X(I) = C(J) 
DO 10 I=2,N 

X(I+INCX) = C(J+INCC)+X(I) 

J = J+INCC 

I = I+INCX 
10 CONTINUE 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

SASUM, SCASUM - Sums the absolute value of elements in a vector 

SYNOPSIS 

sum - SA$UM(n,sx,incx) 
sum = SCA$UM{n t cx,incx) 

DESCRIPTION 

n Number of elements in the vector to be summed. If n < 0, SASUM and SCASUM return 0. 

(input) 

sx Real vector to be summed (input) 

cx Complex vector to be summed (input) 

incx Increment between elements of sx or cx. For contiguous elements, incx^l. (input) 

SASUM and SCASUM sum the absolute values of the elements of a real or complex vector, respectively. 
SASUM computes 

n 

sum = 2l x k,l 

i=l 

(l+(i-l)(incx), incx>0 
l+(n-i)\ incx\ incx<0 w ^ ere ^ m element of a rea l vector. 

SCASUM computes 

n 

sum = X [ |real (x kj )| + |imag(x t .)| ] 

i=l 

where k- t is as defined for SASUM. x k , is an element of a complex vector. 

Note that SASUM computes a true l\ norm, but SCASUM does not 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
EXAMPLES 

REAL SUM,SUMMER(10) 

SUMMER(1)=0.0 

DO 10 1=2,10 

SUMMER(I)=SUMMER(I-1)+ 1.0 
10 CONTINUE 

SUM=SASUM(5,SUMMER,2) 

PRINT*, SUM 

STOP 

END 

111 the preceding example, SUMMER(1)=0.0, SUMMER(2)=I.O, STJMMER(3)=2.0 > ...SUMMER(10)=9.0. 
The printed result of SUM equals 20.0. 
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NAME 

SAXPY, CAXPY - Adds a scalar multiple of a real or complex vector to another vector 

SYNOPSIS 

CALL SAXVYintSatSxMcXiSyMcy) 
CALL CAXVY(n,ca,cx,incx t cy t incy) 

DESCRIPTION 



n Number of elements in the vectors. If n £ 0, SAXPY and CAXPY return without any compu 
tation. (input) 

sa Real scalar multiplier (input) 

ca Complex scalar multiplier (input) 

sx Real vector to be scaled for sum (input) 

cx Complex vector to be scaled for sum (input) 

incx Increment between elements of sx or cx. For contiguous elements, incx±l. (input) 

sy Real vector used in summation. It receives the resulting vector, (inpui/output) 

cy Complex vector used in summation. It receives the resulting vector, (input/output) 

incy Increment between elements of sy or cy. For contiguous elements, incy±l. (input) 



These subroutines add a scalar multiple of one vector to another. 
SAXPY computes 

(l+(i - l)(incx ), incx >Q \l+(i-l)(incy ), incy >0 

l+(n-i)\incxl incx<0 md Z < = [U( n -i)\incyl incy<D 

where a is a real scalar multiplier and and yt. are elements of real vectors. 

CAXPY computes 

jyz. - axjt, + yi t > i-1,..., n and Jfc, and 4 are as defined for SAXPY. 

where a is a complex scalar multiplier and x k . and yi. are elements of complex vectors. 
When n<0 , sa=0 7 or ca=0+0z, these routines return immediately with no change in their arguments. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

SSCAL, CSSCAL, CSCAL - Scales a real or complex vector 

SYNOPSIS 

CALL SSCAL(n,sa,sx,incx) 
CALL CSSCAL(n,sa,cx,incx) 
CALL CSCAL(n,ca f cx t incx) 

DESCRIPTION 



n Number of elements in the vector. If n < 0, SSCAL, CSSCAL, and CSCAL return without 
any computation, (input) 

sa Real scaling factor (input) 

ca Complex scaling factor (input) 

sx Real vector to be scaled (input/output) 

cx Complex vector to be scaled (input/output) 

incx Increment between elements of sx or cx (input) 



These subroutines scale a vector. 

SSCAL computes 
X = aX 

where a is a real number and X is a real vector. 

CSSCAL computes 
X = aX 

where a is a real number and X is a complex vector. 

CSCAL computes 
Y = a Y 

where a is a complex number and Y is a complex vector. 
IMPLEMENTATION 

These routines are available to users of both the COS and UMCOS operating systems. 
CAUTIONS 

Do not specify incx as zero; doing so yields unpredictable results. 
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NAME 

SCATTER - Scatters a vector into another vector 

SYNOPSIS 

CALL SCAJTEU(n,a,index t b) 

DESCRIPTION 

n Number of elements in vectors index and b (not in a) (input) 

a Resulting vector (output) 

index Vector of indices (input) 

b Source vector (input) 

SCATTER is defined as follows: 

aj = bi where i = 1, . . n 

In Fortran: 

DO 100 I-1.N 

A(DSfDEX(I))=B(I) 
100 CONTINUE 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

SCOPY, CCOPY - Copies a real or complex vector into another vector 

SYNOPSIS 

CALL $COVY(n t sx,incx,sy>incy) 
CALL CCOW(n,cxMcx,cy t incy) 

DESCRIPTION 

n Number of elements to be copied. If n < 0, SCOPY and CCOPY return without any compu- 

tation, (input) 

sx Real vector to be copied (input) 

cx Complex vector to be copied (input) 

incx Increment between elements of sx or cx; for contiguous elements, incx = ± 1 (input) 

sy Real result vector (output) 

cy Complex result vector (output) 

incy Increment between elements of sy or cy; for contiguous elements, incy = ± 1 (input) 

These subroutines copy one vector into another. 
SCOPY copies a real vector 

incx>0 t l+(/-lXmcy). incy>0 

where = | 1+ ( rt _/)| inci: | t i„ cx< Q and = incy< Q 

and x k . and yi. are elements of real vectors. 
CCOPY copies a complex vector 

where Jfc, and /,• are as defined in the previous example, and x kj and y t _ are elements of complex 
vectors. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

SGBMV - Multiplies a real vector by a real general band matrix 
SYNOPSIS 

CALL SGBMy(trans t m t nMMfalpha t aJda^4ncx f beta t y,incy) 

DESCRIPTION 

SGBMV performs one of the matrix-vector operations 

y :=aipha*a*x +beta*y or y \=alpha*d*x +beta*y 

Arguments alpha and beta are scalars, x and y are vectors, a is an m-by-n band matrix, with kl subdiag- 
onals and ku superdiagonals, and a' denotes the transpose of a. 

trans Character*!, On entry, trans specifies the operation to be performed If trans =N* or V, 
y := alpha* a*x +beta*y . If trans=V or *t\ y := alpha*d*x+beta*y . The trans argument is 
unchanged on exit. 

m Integer, On entry, m specifies the number of rows of the matrix a. m must be at least zero. 
The m argument is unchanged on exit. 

n Integer* On entry, n specifies the number of columns of the matrix a. n must be at least zero. 
The n argument is unchanged on exit. 

kl Integer. On entry, Id specifies the number of subdiagonals of the matrix a. kl must satisfy 
0-LEjU. The kl argument is unchanged on exit 

ku Integer. On entry, ku specifies the number of superdiagonals of the matrix a. ku must satisfy 
OXEJfew. The ku argument is unchanged on exit 

alpha Real. On entry, alpha specifies the scalar alpha. The alpha argument is unchanged on exit 

a Real array of dimension (Idaji). Before entry, the leading 0W+£n+l)-by-n part of the array a 
must contain the matrix of coefficients, supplied column-by-column, with the leading diagonal 
of the matrix in row (iu+1) of the array, the first superdiagonal starting at position 2 in row ku y 
the first subdiagonal starting at position 1 in row (ku+2) > and so on. Elements in the array a 
that do not correspond to elements in the band matrix (such as the top left ku-by-ku triangle) 
are not referenced. The following program segment will transfer a band matrix from conven- 
tional full matrix storage to band storage: 

DO 20, J=1,N 
K » KU+l-J 

DO 10, I =MAX ( 1 , J - KU ) , MIN(M,J+KL) 
A(K+I , J ) = MATRIX( I , J ) 
10 CONTINUE 
2 0 CONTINUE 

The a argument is unchanged on exit. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling 
(subprogram. Ida must be at least (kl+ku+l). The Ida argument is unchanged on exit. 

x Real array of dimension at least l+(nA)*\incx\ when trans=W or V and at least 

l+(m-l)*|//icx| otherwise. Before entry, the incremented array x must contain the vector Jt. 
The x argument is unchanged on exit 
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incx Integer. On entry, incx specifies the increment for the elements of x. The incx argument must 
not be zero. The incx argument is unchanged on exit 

beta Real On entry, beta specifies the scalar beta. When beta is supplied as zero* y need not be set 
on input. The beta argument is unchanged on exit. 

y Real anray of dimension at least l+(m-l)*\incy\ when trans=N y or V and at least 

l+(n-l)*|mcy| otherwise. Before entry, the incremented array y must contain the vector y. On 
exit, y is overwritten by the updated vector y. 

incy Integer. On entry, incy specifies the increment for the elements of y. incy must not be zero. 
The incy argument is unchanged on exit 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTE 

SGBMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

SGEMM - Multiplies a real general matrix by a real general matrix 
SYNOPSIS 

CALL SGEMM (transa .transb ,m t n ,k, alpha ,a,lda t b,ldb,beta t c,ldc) 

DESCRIPTION 

SGEMM performs one of the matrix-matrix operations: 

c := alpha*op(a)*op(b)+beta*c 

where op(x) is one of the following: 

opto = 
or op(x) - x* 

Arguments alpha and beta are scalars, a, b, and c are matrices, op(a) is an m-by-Jfc matrix, op{b) is 
a k-by-n matrix, and c is an m-by-n matrix. 

transa Type character* 1 . 

On entry, transa specifies the form of op(a) to be used in the matrix multiplication as follows: 

If transa - *N* or *n\ op(a) = a. 
If transa = T f or V, op(a) = a\ 
If transa = *C* or *c\ op(a) = a\ 

On exit, transa is unchanged. 

transb Type character*!. 

On entry, rron^fe specifies the form of op(b) to be used in the matrix multiplication as follows: 

If transb = % N* or V, op(6) = fe. 
If transb = T or V, op(b) = 6'. 
If fra/uft = 'C* or V, op(6) = b\ 

On exit, fran^i is unchanged. 

m Type integer. 

On entry, m specifies the number of rows in matrix op(a) and in matrix c. 
Argument m must be at least 0, 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in matrix op(b) and in matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry, k specifies the number of columns of matrix op(a) and the number of rows of matrix 
op(fe). 

Argument k must be at least 0. 
On exit, k is unchanged. 
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alpha Type real. 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

a Type real. 

Array of dimension (Ida, ka). 

Argument ka is k when transa - W or V, and is m otherwise. 

Before entry with transa = *N* or 5 n\ the leading m-by-k part of array a must contain matrix a. 
Otherwise, the leading k-by~m part of array a must contain matrix a. 
On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
When transa = *N' or *n\ Ida must be at least max(l, m). 
Otherwise, Ida must be at least max(l, k). 
On exit, Ida is unchanged. 

b Type real. 

Array of dimension (Idb, kb). 

Argument kb is n when transb « *N' or V, and is k otherwise. 

Before entry with transb = 'N ? or *n\ the leading k-by-n part of array b must contain matrix b. 
Otherwise, the leading n-by-Jfc part of array b must contain matrix b. 
On exit, b is unchanged. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (sub)program. 
When transb = 'N* or V, Idb must be at least max(l, k). 
Otherwise, Idb must be at least max(l, n). 
On exit, Idb is unchanged. 

beta Type real. 

On entry, beta specifies the scalar beta. 

When beta is supplied as 0, c need not be set on input. 

On exit, beta is unchanged. 

c Type real. 

Array of dimension (ldc 9 n). 

Before entry, the leading m-by-n part of array c must contain matrix c, except when beta is 0, 
in which case c need not be set on entry. 

On exit, array c is overwritten by the m-by-n matrix (alpha* op(a)*op(b)+beta*c). 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (subprogram. 
Argument Idc must be at least max(l, m). 
On exit, Idc is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTES 

SGEMM is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 

SEE ALSO 

SGEMMS(3COS) 
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NAME 

SGEMMS - Multiplies a real general matrix by a real general matrix using Strassen's algorithm 
SYNOPSIS 

CALL SGEMMS(transa t transb,m t nXalpha,aMa>bJdbfata t cJdcw 
DESCRIPTION 

Routine SGEMMS is functionally equivalent to SGEMM, except for an additional parameter, work. The 
primary difference is that SGEMMS is implemented using Winograd's variation of Strassen's algorithm 
for matrix multiplication, which is significantly faster for large matrices. 

Strassen's algorithm for matrix multiplication is a complex, recursive algorithm that performs the multi- 
plication in a manner completely different from the usual inner product method. While the inner pro- 
duct method requires a number of operations on the order of n 3 (where n is the dimension of the 
matrices), Strassen's algorithm requires, in theory, a number of operations on the order of n 2 * 8 . The tra- 
deoff is that Strassen's algorithm requires a work array in memory of size 234* n 2 . Specifically, the 
work array must be of size at least 

2.34*max(m, k)*max(k, n). 

The work array is overwritten, and no diagnostic is given if the supplied array is too small. 

Numerical results from SGEMMS may differ slightly from those of SGEMM, due to a very different 
order of operations carried out by Strassen's algorithm* 

SGEMMS can be called for any values of the parameters that are legal for SGEMM. A performance 
improvement over SGEMM would not be expected, however, unless the minimum of the array dimen- 
sions is at least 128. For small dimensions, performance is approximately the same as SGEMM, 
although there is some slight overhead. 

SGEMMS performs one of the matrix-matrix operations: 
c := alpha*op(a)*op(b)+beta*c 
where opfjc) is one of the following: 

op(x) = x> 
or op(x) * x 9 

Arguments alpha and beta are scalars, a, b, and c are matrices, op(a) is an m-by-ifc matrix, op(b) is 
a k-by~n matrix, and c is an m-by-n matrix. 
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transa Type character*!. 

On entry, transa specifies the forni of op(tf) to be used in the matrix multiplication as follows: 

If transa = 'N* or V, op(a) = a. 
If transa = T f or Y, op(a) = a\ 
If transa = 'C or *c\ op(a) = a'. 

On exit, transa is unchanged. 

f ra/irf> Type character* 1 . 

On entry, transb specifies the form of op(6) Id be used in the matrix multiplication as follows: 

If transb = 'N' or V, op(fe) = b. 
If transb = T* or Y, op(b) = 6'. 
If transb = *C* or *c\ op(b) = *\ 

On exit, transb is unchanged. 

m Type integer. 

0*i entry, m specifies the number of rows in matrix op(a) and in matrix c. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in matrix op(i) and in matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry, k specifies the number of columns of matrix op(#) and the number of rows of matrix 
op(6). 

Argument k must be at least 0. 
On exit, k is unchanged. 

alpha Type real 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

a Type real. 

Array of dimension {Ida, ka). 

Argument ka is k when transa = *N* or *n\ and is m otherwise. 

Before entry with transa = 'N* or V, the leading m-by-k part of array a must contain matrix a. 
Otherwise, the leading k-by-m part of array a must contain matrix a. 
On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
When transa = *N' or *n\ Ida must be at least max(I, m). 
Otherwise, Ida must be at least max(l, k). 
On exit, Ida is unchanged. 

b Type real. 

Array of dimension (Idb, kb). 

Argument kb is n when transb = 'N* or *n\ and is k otherwise. 

Before entry with transb = *N* or 'n\ the leading k-by-n part of array b must contain matrix b. 
Otherwise, the leading n-by-k part of array b must contain matrix b. 
On exit, b is unchanged. 
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Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (subprogram. 
When transb - *N' or V, Idb must be at least max(l, k). 
Otherwise, Idb must be at least max(l, n). 
On exit, Idb is unchanged. 

beta Type real. 

On entry, beta specifies the scalar beta. 

When beta is supplied as 0, c need not be set on input 

On exit, beta is unchanged. 

c Type real. 

Array of dimension (ldc 9 n). 

Before entry, the leading m-by-/i part of array c must contain matrix c, except when beta is 0, 
in which case c need not be set on entry. 

On exit, array c is overwritten by the m-by-n matrix (alpha* op(a)*op(b)+beta*c). 
Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (sub)program. 
Argument Idc must be at least max(l, m). 
On exit, Idc is unchanged. 

work Type real. 

Array of dimension at least 2,34*max(m, Jfc)*max(A;, n). 
Used for intermediate calculations. 
On exit, work is overwritten. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTES 

SGEMMS is a CRI extension to the standard level 3 Basic Linear Algebra Subprograms (BLAS 3). 

SEE ALSO 

SGEMM(3COS) 
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NAME 

SGEMV - Multiplies a real vector by a real general matrix 
SYNOPSIS 

CALL $GEMV(trans t m,n,alpha t aJdaj,incx,beta,y t incy) 

DESCRIPTION 

SGEMV performs one of the matrix-vector operations 

y := alpha*a*x + beta*y> or y := alpha*a* *x + beta*y 

Arguments alpha and beta are scalars, x and y are vectors, a is an m-by-n matrix, and a* is the transpose of a. 

trans Character* 1 . On entry, trans specifies the operation to be performed. 
If trans= 9 N* or 'n\y := alpha*a*x + beta*y. 
If trans='T or *t\ y := alpha*a f *x + fte/a*y. 
The rra/i^ argument is unchanged on exit. 

m Integer. On entry, m specifies the number of rows of the matrix a, m must be at least 0. The m 
argument is unchanged on exit. 

* Integer. On entry, n specifies the number of columns of the matrix a. n must be at least 0, The n 
argument is unchanged on exit 

alpha Real. On entry, alpha specifies the scalar alpha. The alpha argument is unchanged on exit. 

a Real array of dimension (lda,n). Before entry, the leading m-by-n part of the array a must contain 
the matrix of coefficients. The a argument is unchanged on exit. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling subprogram. Ida 
must be at least max(l /n). The Ida argument is unchanged on exit 

x Real array of dimension at least l+(*-l)*|mcx| when trans='N* or y n 9 and at least l+(m-l)*|i/icx| 
otherwise. Before entry, the incremented array x must contain the vector x. The jc argument is 
unchanged on exit 

incx Integer. On entry, incx specifies the increment for the elements of x. incx must not be 0. The incx 
argument is unchanged on exit 

beta Real. On entry, beta specifies the scalar beta. When beta is supplied as 0 then y need not be set on 
input The beta argument is unchanged on exit. 

y Real array of dimension at least l+(m-l)*|mcy| when trans=*N' or V and at least l+(n-l)*\incy | 
otherwise. Before entry with beta nonzero, the incremented array y must contain the vector y. On 
exit, y is overwritten by the updated vector y. 

incy Integer. On entry, incy specifies the increment for the elements of y. incy must not be 0. The incy 
argument is unchanged on exit 

IMPLEMENTATION 

This routine is available to users of both the COS and UMCOS operating systems. 

NOTES 

SGEMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

SGER - Performs rank 1 update of a real general matrix 

SYNOPSIS 

CALL $GER(m,n,alpha#,mcx t y,incy,a,lda) 

DESCRIPTION 

SGER performs the rank 1 operation 

a := alpha*x*y' + a 

where x is an m element vector, y is an n element vector, a is an m-by-n matrix, and y is the transpose of y. 

m Integer. On entry, m specifies the number of rows of the matrix a. m must be at least 0. Unchanged 
on exit. 

n Integer. On entry, n specifies the number of columns of the matrix a. n must be at least 0. 
Unchanged on exit 

alpha Real. On entry, alpha specifies the scalar alpha. Unchanged on exit. 

x Real. Array of dimension at least l+(/n-l)* | incx\. Before entry, the incremented array x must con- 
tain the m element vector x. Unchanged on exit 

incx Integer. On entry, incx specifies the increment for the elements of x. incx must not be 0, 
Unchanged on exit 

y Real, Array of dimension at least 1 +(*-!)* \incy |. Before entry, the incremented array y must con- 
tain the n element vector y. Unchanged on exit 

incy Integer. On entry, incy specifies the increment for the elements of y. incy must not be 0. 
Unchanged on exit 

a Real array of dimension (lda 9 n). Before entry, the leading m-by-n part of the array a must contain 
the matrix of coefficients. On exit, a is overwritten by the updated matrix. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling subprogram. Ida 
must be at least max(l^n). Unchanged on exit 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

SGER is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

SMXPY - Multiplies a column vector by a matrix and adds the result to another column vector 

SYNOPSIS 

CALL SMXVY(nly,n2,ldmjc,m) 

DESCRIPTION 



nl Number of elements in vector y and number of rows in matrix m (input) 

y Real vector of length nl which is added to the product of m and x. It is overwritten by the 
resulting vector, (input/output) 

ri2 Number of elements in vector x and number of columns in matrix m (input) 

Idm Leading dimension of matrix m (input) 

x Real vector of length n2 used in the matrix-vector product (input) 

m nl -by -n2 matrix used in the matrix- vector product (input) 



SMXPY performs the matrix-vector operation: 
y := y + m*x 

where y is a vector of length nU m is an nl -by -n2 matrix, and x is a vector of length *2. 

SMXPY executes an operation equivalent to the following Fortran code: 

SUBROUTINE SMXPY(Nl,Y,N2iDM,X t M) 
REAL Y(l), X(l), M(LDM,1) 
DO 20 J=1>N2 

DO 20 1=1 JSfl 

Y(I>Y(I) + X(J) * M(I J) 

20 CONTINUE 
RETURN 
END 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

SNRM2, SCNRM2 - Computes the Euclidean norm of a vector 

SYNOPSIS 

eucnorm = SNRM2(n,sx,incx) 
eucnorm - SCNRM2(w,c* r />icx) 

DESCRIPTION 

n Number of elements in vector x for which to compute norm. If n < 0, SNRM2 and SCNRM2 

return without any computation, (input) 

sx Real vector of length at least l+(/i-l)*|mcx:| containing operand vector x (input) 

cx Complex vector of length at least l+(n-l)*| incx\ containing operand vector x (input) 

incx Increment between elements of sx or cx (input) 

These real functions compute the Euclidean or l 2 norm of vector x as follows: 
SNRM2 computes 



eucnorm = 



SCNRM2 computes 



eucnorm = 



X Xi Xi 

i=l 



Xi is the complex conjugate of jc f . 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

SOLR, SOLRN, SOLR3 - Solves second-order linear recurrences 

SYNOPSIS 

CALL SOlJR{n t sa t inca ) sb t incb f sc 1 incc) 
result = SOlJ!LN(n,saMca t sbMcb,scMcc) 
CALL $OLR3(n>sa t inca t sbjncb r scMcc) 

DESCRIPTION 



n Length of linear recurrence. If n < 0, SOLR and SOLR3 return without any computation, 

and SOLRN returns 0 (input) 

sa Vector of length at least l+(n-l)*\inca\ containing vector operand a (input) 

inca Increment between elements of vector sa (input) 

sb Vector of length at least l+(n-l)*|/nc6| containing vector operand b (input) 

incb Increment between elements of vector sb (input) 

sc Vector of length at least l+(n-l)*|ma;| containing resulting vector c. 

Values for C(l) and C(2) are input to these routines, (input/output) 

incc Increment between elements of vector sc (input) 



SOLR solves a second-order linear recurrence. 

SOLRN solves a second-order linear recurrence for the last term only. 

SOLR3 solves a second-order linear recurrence for three terms. 



SOLR solves second-order linear recurrences as in the following equation: 
Ci = tf,'-2 Ci-i + k-2 Ci-2 for *-3, . . , n 

Note that ci and c% are input to this routine, and c 3) c 4> . . c n are output. 



SOLRN, a real function, solves for only the last term of a second-order linear recurrence, as given 
above for SOLR. 

The Fortran loop 

DO 10 1=3 ,N 

Ca)=A(I-2)*C(I-l)+Ba-2)*C(I-2) 
10 CONTINUE 
RESULT=C(N) 

could be solved as follows: 

result = SQLKN{n&lJb f hcA) 

For SOLRN, even though only the last term is computed, vector c is used to hold intermediate results 
and is therefore overwritten. 
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S0LR3 computes a second-order linear recurrence of three terms, as in the following: 

Ci = Ci + Oi_ 2 Ci-i + *i-2 Ci-2 for i=3, . . . n 
c\ and C2 are input to this routine, and c 3t c 4> . . c n are output. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
CAUTIONS 

Do not specify inca* inch, or incc as zero; doing so yields unpredictable results. 

EXAMPLES 

Example 1 - SOLRN: 

SOLRN might be used to find r 2 of the calculation 
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with the following call: 

R2 = SOLRN(n,a,l,&,l,c,l) 

The Fortran equivalent for example 1 is as follows: 

R1=C(1) 
R2=C(2) 
DO 10 I=l,N-2 

TEMP=R2 

R2=A(I)*R2+B(I)*R1 
R1=TEMP 
10 CONTINUE 
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Example 2 - SOLR3: 

S0LR3 solves a system of lower bidiagonal linear equations Lx=b. That is, since 
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can be written as: 
x 2 = b z -eix 1 

Xi=bi- e.-i^-i - f i-%Xi-2 i=3 n 

this problem can be solved with the following Fortran: 

DO 10 I=1,N-1 
10 E(I)=-E(I) 

DO 20 I=l,N-2 
20 F(I)=-F(I) 

B(2)=B(2)+E(1)*B(1) 

CALL SOLR3(N,E(2),l^(l),l,B(l),l) 
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NAME 

SPDOT, SPAXPY - Performs sparse vector operations 

SYNOPSIS 

pdot - S?DOT(n,sy,index t sx) 
CALL SFAXPYinja^syjndex) 

DESCRIPTION 
SPDOT: 

Performs a sparse dot product (inner product) computation. 

n Number of elements to be used in the computation (input) 

sy Sparse real vector operand (input) 

index Vector of indices for elements of sy in ascending order (input) 

sx Real vector operand (input) 

SPAXPY: 

Performs an elementary vector operation by adding a scalar multiple of a vector to a sparse vector. 

n Numbers of elements to be used in the computation (input) 

sa Real scalar multiplier (input) 

sx Real vector operand scaled for sum (input) 

sy Sparse real vector used in summation and resulting vector (input/output) 

index Vector of indices for elements of sy. All values in index should be unique and in ascending 
order, (input) 

SPAXPY executes an operation equivalent to the following Fortran code: 

DO 10 I=1,N 

SY(INDEX(I))=SA*SX(I)+SY(INDEX(I)) 
10 CONTINUE 

SPDOT executes an operation equivalent to the following Fortran code: 

PDOT=0.0 
DO 10 I=1,N 

PDOT=PDOT+SY(INDEXa))*SX(I) 
10 CONTINUE 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

RETURN VALUE 

If n <, 0 f SPAXPY and SPDOT return without any computation. 
If .sa = 0, SPAXPY returns without any computation. 
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NAME 

SROT - Applies an orthogonal plane rotation 

SYNOPSIS 

CALL $ROT(n t sx t incx>syMcy,c t s) 

DESCRIPTION 

n Number of vector elements on which to apply rotation (input) 

sx Real vector to be modified of length at least l+(n-l)*| wcjc[ (input/output) 

incx Increment between elements of sx (input) 

sy Real vector to be modified of length at least l+(n-l)*|z>icy| (input/output) 

incy Increment between elements of sy. For contiguous elements, incy = 1. (input) 

c Real cosine of rotation. Normally calculated using SROTG. (input) 

s Real sine of rotation. Normally calculated using SROTG. (input) 

This subroutine applies a matrix plane rotation. If the coefficients c and s satisfy c*c+s*s = 1.0, the 
transformation is a Givens rotation. The coefficients c and s can be calculated from the elements of a 
two-element vector that determine the angle of rotation using SROTG, 

SROT applies to each pair of elements Xi and y t in the following plane rotation: 



SROT returns without modifying any input parameters if c ^ 1 and 5 = 0. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems, 

SEE ALSO 

SROTG<3SCI) 
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NAME 

SROTG - Constructs a Givens plane rotation 

SYNOPSIS 

CALL SROTG(0,& f c,*) 

DESCRIPTION 

a First scalar element of the two-element vector that determines the angle of rotation 

(input/output) 

b Second scalar element of the two-element vector that determines the angle of rotation 

(input/output) 

c Cosine of rotation (output) 

s Sine of rotation (output) 

SROTG computes the elements of a rotation matrix such that: 

The above call calculates the parameters r, z, c, and s from input coordinates a, b as in the following: 



(sgn(a) if | a | >| b \ 
sgn(b) if \a\<\b\ 



r m <s(a 2 +b*)* 



c = 



\air ifr*0 
1 ifr=0 



s = 



\blr if r 
[0 ifr 



*0 
=0 



a is not needed in computing a Givens rotation matrix; however, its use permits later reconstruction of 
c and s from just one number. For this reason parameter z is also calculated as follows: 

r 

s if|a|>|*| 
2 = 11/c if \a \ <\b I and c *0 
1 if c = 0 

The subroutine uses parameters a and b and returns r, z, c, and s, where r overwrites a, and z 
overwrites b. 
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A later reconstruction of c and s from z can be done as follows: 
If z = 1 , set c = 0 and 5 = 1 
If | z | < 1 , set c = (1-z 2 )* and s = z 
If j z | > 1 , set c — 1/z and jf = (l-c 2 )^ 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

SROT(3SCI), CROT(3SCI) 
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NAME 

SROTM - Applies a modified Givens plane rotation 

SYNOPSIS 

CALL SROTM(n 9 sxMcx,syMcy t param) 

DESCRIPTION 



n 


Number of elements on which to apply rotation (input) 


sx 


Real vector to be modified of length at least l+(n-l)*|mcjc| (input/outpot) 


incx 


Increment between elements of sx (input) 


sy 


Real vector to be modified of length at least l+(n-l)*\incy\ (input/output) 


incy 


Increment between elements of sy (input) 


param 


5-element vector containing rotation matrix information (input) 



SROTM applies the modified Givens plane rotation constructed by SROTMG. 
It computes 









1 


r -y 


Xi 














h 21 




H 



where the parameters Hll, H21, H12, and H22 are the elements of the rotation matrix H, and are passed 
in the array PARAM according to the following schedule: 

PARAM(l) is the key parameter having values 1.0, 0.0, -1.0, or -2.0. 
Case for which PARAM<1)=1.0: 

H11=PARAM(2) 

H2U-1.0 

H12=1.0 

H22=PARAM(5) 
and PARAM(3) and PARAM(4) are ignored. 
Case for which PARAM(1)=0.0: 

Hll=1.0 

H21=PARAM(3) 

H12=PARAM(4) 

H22=1.0 



and PARAM(2) and PARAM(S) are ignored. 
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Case for which PARAM(1)=-1,0 is rescaling case, so: 

H11=PARAM(2) 

H21=PARAM(3) 

H12=PARAM(4) 

H22=PARAM(5) 
is a full matrix multiplication. 
Case for which PARAM(1)=2.0 is H=I, namely: 

H11=L0 

H2 1=0.0 

H12=0.0 

H22=1.0 

and PARAM(2), PARAM(3), PARAM(4), and PARAM(5) are ignored. 

If n < 0, or if H is an identity matrix, SROTM returns with no operation on input arrays sx and sy. 

If any other value for PARAM(l) is read (other than 1., 0, -1., or -2.)» SROTM aborts the job with the 
following message appearing in the logfile: 

SROTM CALLED WITH INCORRECT PARAMETER KEY 

The array PA RAM must be declared in a dimension statement in the calling program, as follows: 
DIMENSION PARAM(5) 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

See the description of SROTMG(3SCI) for further details about the modified Givens transformation and 
the array PARAM. 
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NAME 

SROTMG - Constructs a modified Givens plane rotation 

SYNOPSIS 

CALL SROTMG(tf i, d 2 , b u b 2 , param) 

DESCRIPTION 

d u d 2 f t>u *2 ** eal quantities that define a 2-element vector in partition form as given below 
(input/output) 

param 5-element vector containing rotation matrix information (output) 



SROTMG computes the elements of a modified Givens plane rotation matrix. 

SROTMG sets up the computed elements in param from inputs d u d 2 ,b l% and b 2 . 

The algorithm for SROTMG is based on the observation that an application of the Givens plane rotation 

G 



can be written in a form such that repeated applications require matrix multiplications by matrices con- 
taining only two nonunit elements. Thus, row transformations require only 2N rather than 4N multipli- 
cations. This application uses the input quantities d u d 29 b u and b 2 to define a 2-element vector in 
partitioned form as 





VH7 o' 






1 

= ° 2 






0 V<*2 











where d y and d 2 are scale factors, and the scaling upon each application of matrix G is updated. 
Let H be a matrix 



H = 



such that 



G \x 



An * 12 
A 21 A 22 



= D /2 H 



61 



where Z>' 2 = diag 
to equation 3 or 4. 



contains the updated scale factors; therefore, H is chosen according 



Equation 3: 

61 



D' 2 H 



bi 
b 2 
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Equation 4: 



^Jd 7 !* h 2 \ V?2* A22 -V37s d 2 c 

v. > v j 



Coefficients c and s are determined by equations 5 and 6. 



Equation 5: 



x 



c = 




Equation 6: 




S = 



Equation 4 shows that the d's are going to be scaled by c or s if two of the K s are to be unity. 

Two cases, | c \ > \ s | and | s \ £ \ c | , are considered so that the <Ts are scaled down the least upon 
repeated applications. 



If I c I > I 5 I (which from equations 5 and 6 is the same as | d\b f | > | d 2 b 2 \ )> the solutions for equa- 
tion 4 are determined by equation 7. 

Equation 7: 

An = A 22 = 1 
Case 2: 

If I s \ £ I c I (which is | d 2 b} I ^ I d { b l | ), equation 8 is chosen. 
Equation 8: 

A12 = "A 21 = 1 

Distinguishing the two cases | c \ > or | s \ > — is the updating factor. Then the complete solu- 
tions for D' 2 and H are as follows: 

Case 1: 

In case 1, where | c | > | s | or | d \b\ | > | d 2 b 2 | , the following solutions for H are chosen: 



Case 1: 



An = 1 



<*2*2 



SR-0113 



4-127 



D 



SROTMG(3SCI) 



SROTMG(3SCI) 



~i>2 

h 2l = —j— h 22 = 1 

and scale factors d u d 2 are updated to 

d\ = d x l u - c 2 di 
<i' 2 ~ d 2 / u = c 2 d 2 

where 

u - rfe* (H) = 1 - -2_£ 

and x 7 becomes fc'^^-w . 
Case 2: 

In case 2, where | s \ ^\c | or | d \b f | < | d 2 b 2 | , the following solutions for H are chosen: 
d 1 b 1 

h u = h n = 1 

a 2 b 2 

bi 

h 2] = -I h = — 

Scale factors d\ are updated to 
d\ = d 2 lu 
d' 2 = d { /u 

with 

u = <fer (H) = 1 + 



'2 "2 

and the x ' factor becomes b \ - b 2 -u . 
Case 3: 

Let m = 4096. Whenever the parameters rf, are updated to be outside the window 

(mT 2 <\d\ |<(m) 2 fori = 1,2 

which preserves about 36 - 48 - 12 bits or 10 decimal digits of precision, all parameters are rescaled 
such that the rf, 's are within that window. If either of the rf/s is 0, however, no rescaling action is 
taken. 
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Underflow: 

If | d'i | < (m)~ 2 , the following rescaling is done: 

d\ : = d'i . (m) 2 h' n : = h' n . (mT 1 h' i2 : = k' i2 . (mT l 

and if i=l, b\ : = b\ . (m)' 1 
Overflow: 

If | d'i | > (m) 2 , the following rescaling is done: 

d\ : = d' ( . (mT 2 h' a : = h' n . (m) h' i2 : = h' i2 . (m) 

and if x = 1, 6'j : = b\ . (m) 

Thus, SROTMG modifies the input parameters Dl, D2, and Bl and returns the array PARAM according 
to the following cases: 

Case SI: 

If ABS(D1*B1*B1).GT.ABS(D2«B2*B2), then 

PARAM(1)=0 
PARAM(3)=-B2/B1 
PARAM(4)=D2*B2/D1 *B 1 

and parameters Dl, D2, and Bl are written over by 

D1=D1/U 
D2=D2/U 
B1=B1*U 

where 

U=l .4<D2*B2*B2)/(D1*B 1*B 1). 
Case S2: 

If ABS(D2*B2*B2).GE.ABS(D1*B1*B1), then 
PARAM(1)=1. 

PARAM(2>=(D1*B1)/(D2*B2) 
PARAM(5)=B1/B2 

and parameters Dl, D2, and Bl are written over according to the following sequence: 

TEMP=D1/U 

D1=D2/U 

B1=B2*U 

U=1.+(D1*B1*B1V(D2*B2*B2) 
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Case S3: 

If, in either case SI or case S2, the updated parameters Dl and D2 have been rescaled below/above the 
window 

(m)**(-2).LE.ABS(Dl).LE.(m)**2 
(m)**<-2).LE.ABS(D2).LE.(m)**2 

then the parameters Dl, Hll, H12, Bl and D2, H21, H22, respectively, are rescaled up/down by factors of 
m. Reseating occurs as many times as necessary to bring Dl or D2 within the preceding window. If Dl 
and D2 are within the window on entry, reseating occurs only once. 

Output parameters are 

PARAM(1)=-1. 

PARAM(2)=H11 

PARAM(3)=H21 

PARAM(4)=H12 

PARAM(5)=H22 

and Dl, D2, and Bl are written over by correctly scaled versions of case S2 or case S3. 

If D1<0, the matrix H=0 is generated (that is, h n = h n = h 2i ~ h 22 = 0). PARAM(1)=-1, and the rest of 
the elements of PARAM contain 0. 

Case S4: 

If D2*B2=0 on entry, then H=l. 
Output is 

PARAM(l)=-2.0 only. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

SROTG(3SCI) 



SR-0113 



4-130 



D 



SSBMV(3SCI) 



SSBMV (3SCI) 



NAME 

SSBMV - Multiplies a real vector by a real symmetric band matrix 
SYNOPSIS 

CALL SSBM\(uph,nAalpha t aJda,x,incx t beta,y t incy) 

DESCRIPTION 

SSBMV performs the matrix-vector operation 

y :=alpha*a*x+beta*y 

where alpha and beta are scalars, x and y are n element vectors, and a is an n-by-n symmetric band 
matrix, with k superdiagonals. SSBMV has the following arguments: 

uplo Character* 1. On entry, uplo specifies whether the upper or lower triangular part of the band 
matrix a is being supplied. When uplo=U 9 or V, only the upper triangular part of array a is 
to be referenced. When uplo=L* or T, only the lower triangular part of array a is to be refer- 
enced. The uplo argument is unchanged on exit 

n Integer. On entry, n specifies the order of the matrix a. The n argument must be at least 0. 
The n argument is unchanged on exit. 

k Integer. On entry, k specifies the number of superdiagonals of the matrix a. k must satisfy 
OXEJfc. The k argument is unchanged on exit 

alpha Real On entry, alpha specifies the scalar alpha. The alpha argument is unchanged on exit. 

a Real array of dimension (Idaji). Before entry with uplo=\J y or V, the leading (Jt+l)-by-n part 
of the array a must contain the upper triangular band part of the symmetric matrix, supplied 
column-by-column, with the leading diagonal of the matrix in row (jfc+1) of the array, the first 
superdiagonal starting at position 2 in row k> and so on. The top left Jfc-by-jfc triangle of the 
array a is not referenced. The following program segment will transfer the upper triangular 
part of a symmetric band matrix from conventional full matrix storage to band storage: 



DO 20 , J=l ,N 
M - K+l - J 

DO 10, I=MAX(1 . J-K) , J 



A(M+I, J) = MATRIX(I, J) 



10 
20 



CONTINUE 
CONTINUE 
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Before entry with upto=V or T, the leading (£+l)-by-n part of the array a must contain the 
lower triangular band part of the symmetric matrix, supplied column-by-column, with the lead- 
ing diagonal of the matrix in row 1 of the array, the first subdiagonal starting at position 1 in 
row 2, and so on. The bottom right k-by-k triangle of the array a is not referenced. The fol- 
lowing program segment will transfer the lower triangular part of a symmetric band matrix 
from conventional full matrix storage to band storage: 

DO 20, J*=1,N 
M = 1 - J 

DO 10, I=J, MIN(N,J+K) 

A(M+I,J) =MATRIX(I,J) 
10 CONTINUE 
20 CONTINUE 

The a argument is unchanged on exit. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling 
(subprogram. Ida must be at least (Jt+1). The Ida argument is unchanged on exit. 

x Real array of dimension at least l+(n-l)*|zncjt|« Before entry, the incremented array x must 
contain the vector jc. The x argument is unchanged on exit. 

incx Integer. On entry, incx specifies the increment for the elements of x. incx must not be 0. The 
incx argument is unchanged on exit. 

beta Real. On entry, beta specifies the scalar beta. The beta argument is unchanged on exit. 

y Real. Array of dimension at least l+(w-l)*|i/jcy|. Before entry, the incremented array y must 
contain the vector y. On exit, y is overwritten by the updated vector y. 

incy Integer, On entry, incy specifies the increment for the elements of y. incy must not be 0. The 
incy argument is unchanged on exit. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

SSBMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

SSUM, CSUM - Sums the elements of a real or complex vector 

SYNOPSIS 

sum = SSUM(n.sx,incx) 
sum = C$UM(n,cx,incx) 

DESCRIPTION 

n Number of elements to be summed. If n ^ 0, SSUM and CSUM return 0. (input) 
sx Real vector of length at least l+(*-l)*| incx\ containing elements to be summed (input) 
cx Complex vector of length at least l+(n-l)*\incx\ containing elements to be summed (input) 
incx Increment between elements of sx or cx (input) 

SSUM computes the sum of the elements in a real vector (sx) specified by incx. 
CSUM computes the complex sum of the elements in a complex vector (cx) specified by incx. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

SSWAP, CSWAP - Swaps two real or complex arrays 

SYNOPSIS 

CALL $SWAF(n,sx,incx,sy,incy) 

CALL CSW AP(n,cx,incx,cy4ncy) 
DESCRIPTION 



n Number of elements to be swapped (input) 

If n < 0, SSWAP and CSWAP return without any computation 

sx Real vector of length at least l+(n-\)*\incx\ (input/output) 

cx Complex vector of length at least l+(n-l)*\incx\ (input/output) 

incx Increment between elements of sx or cx (input) 

sy Real vector of length at least l+(*-l)*|/ncy| (input/output) 

cy Complex vector of length at least l+(*-l)*| incy \ (input/output) 

incy Increment between elements of sy or cy. For contiguous elements, incy=l. (input) 



SSWAP exchanges two real vectors. 
CSWAP exchanges two complex vectors. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

SSYMM - Multiplies a real general matrix by a real symmetric matrix 
SYNOPSIS 

CALL SSYMM(side t uplo t m t n f alpha t aJda,b,ldb,beta t c,ldc) 
DESCRIPTION 

SSYMM performs one of the following matrix-matrix operations: 

c alpha*a*b+beta*c 
or c := alpha*b*a+beta*c 

Arguments alpha and beta are scalars, a is a symmetric matrix, and b and c are m-by-n matrices. 

side Type character* 1 . 

On entry, side specifies whether the symmetric matrix a appears on the left or right in the 
operation as follows: 

If side = *L* or T, c := alpha*a*b+beta*c 
If side = 'R' or Y, c := alpha*b*a+beta*c 

On exit, side is unchanged. 
uplo Type character* 1, 

On entry, uplo specifies whether the upper or lower triangular part of the symmetric matrix a is 
to be referenced as follows: 

If uplo = *U* or V, only the upper triangular part of the symmetric matrix is to be referenced. 
If uplo = *L' or T, only the lower triangular part of the symmetric matrix is to be referenced. 

On exit, uplo is unchanged. 

m Type integer. 

On entry, m specifies the number of rows in matrix c. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged, 

alpha Type real 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 
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a Type real. 

Array of dimension (Ida, ka). 

Argument ka is m when side = *L' or T, and is /i otherwise. 

Before entry with side = *L f or T, the m-by-m part of array a must contain the symmetric 
matrix, such that: 

If uplo = TJ* or V, the leading m-by-m upper triangular part of array a must contain the upper 

triangular part of the symmetric matrix. 

The strictly lower triangular part of a is not referenced. 

If uplo = % U or T, the leading m-by-m lower triangular part of array a must contain the lower 

triangular part of the symmetric matrix. 

The strictly upper triangular part of a is not referenced. 

Before entry with side - > R* or V, the n-by-n part of array a must contain the symmetric 
matrix* such that: 

If uplo - 'IT or V, the leading n-by-n upper triangular part of array a must contain the upper 

triangular part of the symmetric matrix. 

The strictly lower triangular part of a is not referenced. 

If uplo = or T t the leading n-by-n lower triangular part of array a must contain the lower 

triangular part of the symmetric matrix. 

The strictly upper triangular part of a is not referenced. 

On exit, a is unchanged. 
Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
When side = *L* or T, Ida must be at least max(l, m). 
Otherwise, Ida must be at least max(l, n). 
On exit, Ida is unchanged. 

b Type real. 

Array of dimension (ldb 7 n). 

Before entry, the leading m-by-n part of array b must contain matrix b. 
On exit, b is unchanged. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (subprogram. 
Argument Idb must be at least max(l, m). 
On exit, Idb is unchanged. 

beta Type real. 

On entry, beta specifies the scalar beta. 

When beta is supplied as 0, c need not be set on input. 

On exit, beta is unchanged. 

c Type real. 

Array of dimension (ldc t n). 

Before entry, the leading /n-by-n part of array c must contain matrix c, except when beta is 0, 

in which case c need not be set on entry. 

On exit, array c is overwritten by the m-by-n updated matrix. 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (sub)program. 
Argument Idc must be at least max(l, m). 
On exit, Idc is unchanged. 
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IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTES 

SSYMM is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 



SR-0113 



4-137 



D 



SSYMV(3SCI) 



SSYMV(3SCI) 



NAME 

SSYM V - Multiplies a real vector by a real symmetric matrix 
SYNOPSIS 

CALL SSYMV(Mpfo,/i ,alpha ,a t ldaxincx t beta t yincy) 

DESCRIPTION 

SSYMV performs the matrix-vector operation 

y := alpha*a*x + beta*y 

where alpha and beta are scalars, x and y are n element vectors, and a is an n-by-* symmetric matrix. 
SSYMV has the following arguments: 

uplo Character* 1, On entry, uplo specifies whether the upper or lower triangular part of the band matrix 
a is being supplied. When'qpfos'U' or V, only the upper triangular part of array a is to be refer- 
enced. When uplo='U or T, only the lower triangular part of array a is to be referenced. The uplo 
argument is unchanged on exit 

n Integer. On entry, n specifies the order of matrix a. The n argument must be at least 0. The n argu- 
ment is unchanged on exit. 

alpha Real. On entry, alpha specifies the scalar alpha. The alpha argument is unchanged on exit. 

a Real. Array of dimension (Idaji). Before entry with uplo='XJ y or *u\ the leading *-by-n upper tri- 
angular part of array a must contain the upper triangular part of the symmetric matrix and the 
strictly lower triangular part of a is not referenced. Before entry with uplo=?U or T, the leading 
n-by-n part of the array a must contain the lower triangular part of the symmetric matrix and the 
strictly upper triangular part of a is not referenced. The a argument is unchanged on exit. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling subprogram. Ida 
must be at least max(l /i). The Ida argument is unchanged on exit 

x ReaL Array of dimension at least l+(rt-l)*|mcrj. Before entry, the incremented array x must con- 
tain the n element vector x The x argument is unchanged on exit. 

incx Integer. On entry, incx specifies the increment for the elements of x. iViarmustnotbeO. The incx 
argument is unchanged on exit. 

beta ReaL On entry, beta specifies the scalar beta. When beta is supplied as 0, y need not be set on 
input The beta argument is unchanged on exit. 

y Real. Array of dimension at least l+(n-l)*|mcy|. Before entry, the incremented array y must con- 
tain the n element vector y. On exit, y is overwritten by the updated vector y. 

incy Integer. On entry, incy specifies the increment for the elements of y. incy must not be 0. The incy 
argument is unchanged on exit 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

SSYMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

SSYR - Performs symmetric rank 1 update of a real symmetric matrix 

SYNOPSIS 

CALL SSYR(uplo t n&lphapc,incx t a t lda) 

DESCRIPTION 

SSYR performs the symmetric rank 1 operation 

a alpha*x*x' + a 

where alpha is a real scalar, xisan/t element vector, and a is an n-by-n symmetric matrix, 
SSYR has the following arguments: 

uplo Character* 1 . On entry , uplo specifies whether the upper or lower triangular part of array a is to be 
referenced. When uplo=V* or V, only the upper triangular part of array a is to be referenced. 
When uplo=L y or T t only the lower triangular part of array a is to be referenced. The uplo argu- 
ment is unchanged on exit. 

n Integer. On entry, n specifies the number of columns of the matrix a. The n argument must be at 
least 0. The n argument is unchanged on exit* 

alpha Real. On entry, alpha specifies the scalar alpha. The alpha argument is unchanged on exit. 

x Real. Array of dimension at least l+(tf-l)* | incx\. Before entry, the incremented array x must con- 
tain the n element vector Jt. The x argument is unchanged on exit. 

incx Integer. On entry, incx specifies the increment for the elements of jc. Argument incx must not be 0. 
The incx argument is unchanged on exit. 

a Real* Array of dimension (lda,n). Before entry, the leading n-by-n part of array a must contain the 
matrix of coefficients. On exit, a is overwritten by the updated matrix. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling subprogram. 
Argument Ida must be at least max(l ,/t). The Ida argument is unchanged on exit 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

SSYR is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

SSYR2 - Performs symmetric rank 2 update of a real symmetric matrix 
SYNOPSIS 

CALL SSYR2(uplo>n t alphapc t incx,y t incy,aJda) 

DESCRIPTION 

SSYR2 performs the symmetric rank 2 operation 

a := atpha*x*y' +atpha*y*x' +a 

where alpha is a scalar, x and y are n element vectors, and a is an n-by-n symmetric matrix. 
SSYR2 has the following arguments: 

uplo Character*!. On entry, uplo specifies whether the upper or lower triangular part of the band 
matrix a is being supplied. When uplo=Xi y or V, only the upper triangular part of array a is 
to be referenced. When uplo=U or T, only the lower triangular part of array a is to be refer- 
enced. The uplo argument is unchanged on exit. 

n Integer. On entry, n specifies the order of the matrix a. The n argument must be at least 0. 
The n argument is unchanged on exit. 

alpha Real. On entry, alpha specifies the scalar alpha. The alpha argument is unchanged on exit. 

x Real. Array of dimension at least l+(/i-l)*|//t£x|. Before entry, the incremented array x must 
contain the n element vector jc. The x argument is unchanged on exit. 

incx Integer. On entry, incx specifies the increment for the elements of x incx must not be 0. The 
incx argument is unchanged on exit. 

y Real. Array of dimension at least \+{n-Yf\incy\. Before entry, the incremented array y must 
contain the n element vector y. The y argument is unchanged on exit 

incy Integer. On entry, incy specifies the increment for the elements of y. incy must not be zero. 
The incy argument is unchanged on exit. 

a Real. Array of dimension (lda f n). Before entry with uplo=U* or V, the leading n-by-n 
upper triangular part of the array a must contain the upper triangular part of the symmetric 
matrix and the strictly lower triangular part of a is not referenced. On exit, the upper triangular 
part of the array a is overwritten by the upper triangular part of the updated matrix. Before 
entry with uplo=U or T, the leading n-by-n lower triangular part of the array a must contain 
the lower triangular part of the symmetric matrix and the strictly upper triangular part of a is 
not referenced. On exit, the lower triangular part of the array a is overwritten by the lower tri- 
angular part of the updated matrix. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling 
(subprogram. Ida must be at least max(M). The Ida argument is unchanged on exit. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

SSYR2 is a level 2 Basic Linear Algebra Subprogram (BIAS 2). 
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NAME 

SSYR2K - Performs symmetric rank 2k update of a real symmetric matrix 
SYNOPSIS 

CALL SSYR2K(uplojrans/iJc t alpha t aMaAtdb r b€ta t c t ldc) 
DESCRIPTION 

SSYR2K performs one of the following symmetric rank 2k operations: 
c := alpha*a*b* +alpka*b*a* +beta*c 
or 

c alpha+a'+b+alphcPb^a+betcPc 

Arguments alpha and beta are scalars, and c is an n-by-n symmetric matrix. Arguments a and b 
are n-by-k matrices in the first operation listed previously, and k-by-n matrices in the second. 

uplo Type character* 1. 

On entry, uplo specifies whether the upper or lower triangular part of array c is to be refer- 
enced as follows: 

If uplo = *U' or V, only the upper triangular part of c is to be referenced. 
If uplo as X' or T, only the lower triangular part of c is to be referenced. 

On exit, uplo is unchanged. 

trans Type character* 1. 

On entry, trans specifies the operation to be performed as follows: 

If trans - 'N' or 'n\ 

c := alpha*a*b' +alpha*b*a* +beta*c 

If trans = TP or Y, 

c := cdpha^a^b+alphafb^a+beta^c 

If trans = XT or 'c\ 

c := alpha*a'*b+alpha*b'*a+beta*c 

On exit, trans is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry with trans = *N* or V, k specifies the number of columns of matrices a and b. 
On entry with trans = T\ Y, *C\ or 'c\ * specifies the number of rows of matrices a and b. 

Argument k must be at least 0. 
On exit, k is unchanged. 

alpha Type real. 

Chi entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 
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a Type real. 

Array of dimension {Ida, ka). 

Argument ka is k if trans = 'N* or *n\ and is n otherwise. 

Before entry with trans = 'N* or *n\ the leading n-by-i part of array a must contain matrix a. 
Otherwise, the leading Jt-by-/i part of array a must contain matrix a. 

On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 

If trans = *N* or 'n', Ida must be at least max(l, n). 
Otherwise, Ida must be at least max(l, k). 

On exit, Ida is unchanged. 

b Type real. 

Array of dimension (ldb t kb) 

Argument kb is k if trans - *N' or *n\ and is n otherwise. 

Before entry with trans = W or V, the leading n-by-k part of array b must contain matrix 6. 
Otherwise, the leading k-by-n part of array b must contain matrix b. 

On exit, 6 is unchanged. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (sub)program. 

If trans = *N* or "n\ /<ft> must be at least max(l, »). 
Otherwise, must be at least max(l, k). 

On exit, WZ? is unchanged. 

beta Type real. 

On entry, beta specifies the scalar beta. 
On exit, beta is unchanged. 

c Type real. 

Array of dimension (Idc, n). 

Before entry with uplo = TJ* or V, the leading n-by-n upper triangular part of array c must 
contain the upper triangular part of the symmetric matrix. 
The strictly lower triangular part of c is not referenced. 

On exit, the upper triangular part of array c is overwritten by the upper triangular part of the 
updated matrix. 

Before entry with uplo - *L* or T, the leading n-by-n lower triangular part of array c must 
contain the lower triangular part of the symmetric matrix. 
The strictly upper triangular part of c is not referenced. 

On exit, the lower triangular part of array c is overwritten by the lower triangular part of the 
updated matrix. 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (subprogram. 
Argument Idc must be at least max(l, *). 
On exit, Idc is unchanged 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NOTES 

SSYR2K is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 
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NAME 

SSYRK - Performs symmetric rank k update of a real symmetric matrix 
SYNOPSIS 

CALL SSYRK(uplo f trans f n,k t alpha,a f lda t beta t c,ldc) 
DESCRIPTION 

SSYRK performs one of the following symmetric rank k operations: 
c := alpha*a*d +beta*c 
or 

c := alpha*a'*a+beta*c 

Arguments alpha and beta are scalars, and c is an n-by-n symmetric matrix. Argument a is an n-by-A 
matrix in the first operation listed previously, and a i-by-n matrix in the second, 

uplo Type character* 1. 

On entry, uplo specifies whether the upper or lower triangular part of array c is to be refer- 
enced as follows: 

If uplo = 'U* or V, only the upper triangular part of c is to be referenced. 
If uplo = T/ or T, only the lower triangular part of c is to be referenced. 

On exit, uplo is unchanged. 

trans Type character* 1. 

On entry, trans specifies the operation to be performed as follows: 

If trans = *N' or V, 

c := alpha* a*a f +beta*c. 

If trans = T or Y, 

c := alpha*d*a+beta*c. 

If trans = XT or 'c\ 

c := alpha*a'*a+beta*c. 

On exit, f/my is unchanged. 

n Type integer. 

On entry, n specifies the order of matrix c. 
Argument n must be at least 0. 
On exit, n is unchanged. 

k Type integer. 

On entry with trans = *N' or 'n\ k specifies the number of columns of matrix a. 
On entry with trans - T\ Y, *C\ or *c\ k specifies the number of rows of matrix a. 

Argument k must be at least 0. 
On exit, k is unchanged. 
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alpha Type reaL 

On entry, alpha specifies the scalar alpha. 
On exit, alpha is unchanged. 

a Type real 

Array of dimension (Ida, ka). 

Argument ka is k if trans = *N* or *n\ and is n otherwise. 

Before entry with trans = 'N* or V, the leading n-by-k part of array a must contain matrix a. 
Otherwise, the leading k-by-n part of array a must contain matrix a. 

On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 

If trans = 'N* or *n\ must be at least max(l, ri). 
Otherwise, Ida must be at least max(l, Jt). 

On exit, Ida is unchanged 

beta Type real. 

On entry, beta specifies the scalar beta. 
On exit, beta is unchanged. 

c Type real. 

Array of dimension (Wc, n). 

Before entry with uplo = "IT or 'u\ the leading n-by-n upper triangular part of array c must 
contain the upper triangular part of the symmetric matrix. 
The strictly lower triangular part of c is not referenced. 

On exit, the upper triangular part of array c is overwritten by the upper triangular part of the 
updated matrix. 

Before entry with uplo = *L* or T, the leading n-by~n lower triangular part of array c must 
contain the lower triangular part of the symmetric matrix. 
The strictly upper triangular part of c is not referenced. 

On exit, the lower triangular part of array c is overwritten by the lower triangular part of the 
updated matrix. 

Idc Type integer. 

On entry, Idc specifies the first dimension of c as declared in the calling (subprogram. 
Argument Idc must be at least max(l, n). 
On exit, Idc is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTES 

SSYRK is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 
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NAME 

STBMV - Multiplies a real vector by a real triangular band matrix 
SYNOPSIS 

CALL STBM\(uplo t trans,diag t nJt,a,tdajc,incx) 

DESCRIPTION 

STBMV performs one of the matrix- vector operations 

x\=a*x orjc:= a'*x 

where x is an n element vector, and a is an n-by-n unit, or non-unit, upper or lower triangular band matrix, 
with (Jfc+1) diagonals, 

STBMV has the following arguments: 

upto Character* 1 . On entry, uph specifies whether matrix is an upper or lower triangular matrix. When 
uplo^U* or V, a is an upper triangular matrix. When uplo=U or T, a is a lower triangular 
matrix. The uplo argument is unchanged on exit 

trans Character* 1 . On entry, trans specifies the operation to be performed. If trans ~ *N* or *n\ x := a*x. 
If trans = *T or * t * , x := a* *jc. The trans argument is unchanged on exit. 

diag Character* 1. On entry, diag specifies whether or not a is unit triangular. If diag = 'IT or V, a is 
assumed to be unit triangular. If diag = *N' or V, a is not assumed to be unit triangular. The diag 
argument is unchanged on exit. 

n Integer. On entry, n specifies the order of the matrix a. The n argument must be at least 0. The n 
argument is unchanged on exit 

k Integer. On entry with uplo= f U* or f u\ k specifies the number of superdiagonals of the matrix a. 
On entry with uplo=U or T, k specifies the number of subdiagonals of the matrix a. Argument k 
must satisfy 0.LE.A. The k argument is unchanged on exit. 

a Real array of dimension Qdaji ), Before entry with uplo= r V 9 or 'u\ the leading (Jfc+l)-by-/i part of 
the array a must contain the upper triangular band part of the matrix of coefficients, supplied 
column by column, with the leading diagonal of the matrix in row (£+1) of the array, the first super- 
diagonal starting at position 2 in row k y and so on. The top left k-by-k triangle of the array a is not 
referenced. The following program segment will transfer the upper triangular band matrix from 
conventional full matrix storage to band storage: 

DO 20, J=1,N 
M = K+l-J 

DO 10, I=MAX(1. J-K), J 

A(M+I,J) =MATRIX(I,J) 
10 CONTINUE 
20 CONTINUE 

Before entry with uplo=*V or T, the leading (Jfc+l)-by-/i part of the array a must contain the lower 
triangular band part of the matrix of coefficients, supplied column-by-column, with the leading 
diagonal of the matrix in row 1 of the array, the first subdiagonal starting at position 1 in row 2, and 
so on. The bottom right k~by-k triangle of the array a is not referenced. The following program seg- 
ment will transfer a lower triangular band matrix from conventional full matrix storage to band 
storage: 
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DO 20, J=1,N 
M = 1-J 

DO 10, I=J, MIN(N,J+K> 

A(M+I , J ) = MATR IX( I , J) 
10 CONTINUE 
20 CONTINUE 

Note that when diag='U 7 or V the elements of the array a corresponding to the diagonal elements 
of the matrix are not referenced, but are assumed to be unity. The a argument is unchanged on exit. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling subprogram. 
Argument Ida must be at least (£+1). The Ida argument is unchanged on exit. 

x Real array of dimension at least 1)* | incx |. Before entry, the incremented array x must contain 
the n element vector x. On exit, x is overwritten with the transformed vector*. 

incx Integer. On entry, incx specifies the increment for the elements of x. Argument incx must not be 0. 
The incx argument is unchanged on exit, 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

STBMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 



STBS V ~ Solves a real triangular banded system of linear equations 



SYNOPSIS 



CALL STBSV(uplo,trans f diag>nJc,a,tda,x t incx) 



DESCRIPTION 



STBSV solves one of the systems of equations 



a*x = b or a!*x = b 



where b and x are n element vectors, and a is an n-by-n unit, or non-unit, upper or lower triangular band 
matrix, with (jfc+1) diagonals. 

No test for singularity or near-singularity is included in this routine. Such tests must be performed before 
calling this routine. 

uplo Character* 1. On entry, uplo specifies whether matrix is an upper or lower triangular matrix. When 
uplo^V* or V, a is an upper triangular matrix. When uplo-'U or T, a is a lower triangular 
matrix. The uplo argument is unchanged on exit. 

trans Character* 1. On entry, trans specifies the equation to be solved. If trans=W or V, a*jc = b. If 
trans=*V or 't\ a'*x = b. The trans argument is unchanged on exit. 

diag Character* 1. On entry, diag specifies whether or not a is unit triangular. If diag= 9 U* or V, a is 
assumed to be unit triangular. If diag^N* or 'n\ a is not assumed to be unit triangular. The diag 
argument is unchanged on exit 

n Integer. On entry, n specifies the order of matrix a. The n argument must be at least 0. The n argu- 
ment is unchanged on exit 

k Integer. On entry with uplo=U* or V, k specifies the number of superdiagonals of the matrix a. 
On entry with uplo= 9 L* or T, k specifies the number of subdiagonals of the matrix a. Argument k 
must satisfy 0 JLE.i. The k argument is unchanged on exit 

a Real array of dimension (Jda t n), Before entry with uplo= 9 V* or V, the leading (Jfc+l)-by-n part of 
array a must contain the upper triangular band part of the matrix of coefficients, supplied column- 
by-column, with the leading diagonal of the matrix in row (£+1) of the array, the first superdiagonal 
starting at position 2 in row k f and so on. The top £-by-k triangle of array a is not referenced. The 
following program segment will transfer an upper triangular band matrix from conventional full 
matrix storage to band storage: 



DO 20, J=l >N 
M = K+l-J 

DO 10, I«MAX(1, J-K), J 



A(M+I , J) = MATR I X ( I , J ) 



10 

20 



CONTINUE 
CONTINUE 
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Before entry with uplo=V or T, the leading (fc+l)-by-n part of array a must contain the lower tri- 
angular band part of the matrix of coefficients, supplied eolumn-by-column, with the leading diago- 
nal of the matrix in row 1 of the array, the first subdiagonal starting at position 1 in row 2, and so on. 
The bottom right k-by-k triangle of array a is not referenced. The following program segment will 
transfer a lower triangular band matrix from conventional full matrix storage to band storage: 



20 CONTINUE 

Note that when diag=U* or V, the elements of array a corresponding to the diagonal elements of 
the matrix are not referenced, but are assumed to be unity. The a argument is unchanged on exit. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 
Argument Ida must be at least (£+1). The Ida argument is unchanged on exit. 

x Real array of dimension at least l+0t-l)*|wcjc|. Before entry, the incremented array x must contain 
the n element right-hand side vector b. On exit, x is overwritten with the solution vector*. 

incx Integer. On entry, incx specifies the increment for the elements of x. Argument incx must not be 0. 
The incx argument is unchanged on exit. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 



DO 

M 

DO 



20, J=l f N 
1 - J 

10, I=J, MIN(N, J+K) 



10 



A(M+I, J) = MATRIX(I, J) 
CONTINUE 



NOTES 



STBSV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

STRMM - Multiplies a real general matrix by a real triangular matrix 
SYNOPSIS 

CALL STKMM(side t uplo,transa4iag,m,n 1 alpha t aJda,b t ldb) 

DESCRIPTION 

STRMM performs one of the matrix-matrix operations: 

b := alpha*op(a)*b 

or b := alpha*b*op(a) 

Argument alpha is a scalar, b is an m-by-n matrix, a is a unit, or non-unit, upper or lower triangular 
matrix, and opfa) is one of the following: 

op(a) = a, 

or op(a) = a\ 

side Type character*!* 

On entry, side specifies whether op(a) multiplies b from the left or right as follows: 

If side = X r or T, b := atpha*op(a)*b. 
If side = TT or V, b := alpha*b*op(a). 

On exit, side is unchanged. 

uplo Type character* 1 , 

On entry, uplo specifies whether matrix (a) is an upper or lower triangular matrix as follows: 

If uplo = 'IT or V, a is an upper triangular matrix. 
If uplo = 'L' or T, a is a lower triangular matrix. 

On exit, uplo is unchanged. 

transa Type character* L 

On entry, transa specifies the form of op(a) to be used in the matrix multiplication as follows: 

If transa = 'N' or *n\ op(a) « a. 
If transa - T' or V, op(a) = a\ 
If transa = *C or *c\ op(a) = a\ 

On exit, transa is unchanged. 

dtag Type character* 1 . 

On entry, diag specifies whether or not a is unit triangular as follows: 

If diag - *U' or *u\ a is assumed to be unit triangular. 
If diag = 'N' or *n\ a is not assumed to be unit triangular. 

On exit, diag is unchanged. 
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m Type integer. 

On entry, m specifies the number of rows in b. 
Argument m must be at least 0. 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in b. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type real. 

On entry, alpha specifies the scalar alpha. 

When alpha is 0, a is not referenced, and b need not be set before entry. 
On exit, alpha is unchanged. 

a Type real. 

Array of dimension (Ida, k). 

Argument k is m when side - 'L' or T, and is n when side = 'R' or Y. 

Before entry with uplo - *LF or V, the leading Jfc-by-Jfc upper triangular part of array a must 

contain the upper triangular matrix. 

The strictly lower triangular part of a is not referenced. 

Before entry with uplo = *L* or T, the leading Jt-by-i lower triangular part of array a must 

contain the lower triangular matrix. 

The strictly upper triangular part of a is not referenced. 

Note that when diag = *U' or *u\ the diagonal elements of a are not referenced, but are 
assumed to be unity. 
On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (subprogram. 
When side = '1/ or T, Ida must be at least max(l, m). 
When side = *R* or Y, Ida must be at least max(l, n). 
On exit, Ida is unchanged. 

b Type real. 

Array of dimension Qdb, n). 

Before entry, the leading m-by-n part of array b must contain matrix b. 
On exit, b is overwritten by the transformed matrix. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (sub)program. 
Argument Idb must be at least max(l, m). 
On exit, Idb is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTES 

STRMM is a level 3 Basic Linear Algebra Subprogram (BLAS 3). 
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NAME 

STRMV - Multiplies a real vector by a real triangular matrix 
SYNOPSIS 

CALL STRMV(uplo,trans,diag>n t a,tdajc t incx) 

DESCRIPTION 

STRMV solves one of the matrix-vector operations 

x:=a*x orx :=a'*x 

where x is an n element vector, and a is an n-by-n unit, or non-unit, upper or lower triangular band 
matrix. 

uplo Character*!, On entry, uplo specifies whether matrix is an upper of lower triangular matrix. 
When upto=*U' or *u\ a is an upper triangular matrix. When upto=*L 7 or T, a is a lower tri- 
angular matrix. The uplo argument is unchanged on exit. 

trans Character*!. On entry, trans specifies the equation to solved as follows: If tran$='N* or 'n\ 
x:=a*x. If trans^'T or Y, x:=a'*x. The trans argument is unchanged on exit. 

diag Character*!. On entry, diag specifies whether or not a is unit triangular as follows: If 
diag=U* or V, a is assumed to be unit triangular. If diag=W or V, a is not assumed to be 
unit triangular. The diag argument is unchanged on exit. 

n Integer. On entry* n specifies the order of the matrix a. The n argument must be at least 0. 
The n argument is unchanged on exit. 

a Real array of dimension (Idajt). Before entry with uplo=*\S* or *u\ the leading n-by-n upper 
triangular part of the array a must contain the upper triangular matrix and the strictly lower tri- 
angular part of a is not referenced. Before entry with uplo-'V or T, the leading n-by-n lower 
triangular part of the array a must contain the lower triangular matrix and the strictly upper tri- 
angular part of a is not referenced. Note that when diag=U* or *u\ the diagonal elements of 
a are not referenced either, but are assumed to be unity. The a argument is unchanged on exit. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling 
(subprogram. Argument Ida must be at least max(l/i). The Ida argument is unchanged on 
exit 

x Real array of dimension at least l+(n-l)*|wcx|. Before entry, the incremented array x must 
contain the n element vector b. On exit, x is overwritten with the transformed vector x. 

incx Integer. On entry, incx specifies the increment for the elements of jc. Argument incx must not 
be 0. The incx argument is unchanged on exit. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

STRMV is a level 2 Basic Linear Algebra Subprogram (BLAS 2). 
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NAME 

STRSM - Solves a real triangular system of equations with multiple right-hand sides 
SYNOPSIS 

CALL STR$M(side,uplo,transa,diag t m,n t atpha>a t lda t b t ldb) 

DESCRIPTION 

STRSM solves one of the following matrix equations: 

ap(a)*x = alpha*b 

or x*ap(a) = atpha*b 

Argument alpha is a scalar, x and b are m-by-n matrices, a is a unit, or non-unit, upper or lower tri- 
angular matrix, and o$(a) is one of the following: 

op(a) = a, 

or op(a) = a\ 

Matrix x is overwritten on b. 

side Type character*!, 

On entry, side specifies whether op(a) appears on the left or right of x as follows: 

If side = *L' or T, op(a)*x = alpha*b 
If side = *R' or V, x*op(a) = alpha*b 

On exit, side is unchanged. 

uplo Type character* 1 . 

On entry, uplo specifies whether matrix (a) is an upper or lower triangular matrix as follows: 

If uplo = *U' or V, a is an upper triangular matrix. 
If uplo = # L* or T, a is a lower triangular matrix. 

On exit, uplo is unchanged. 

transa Type character* 1 . 

On entry, transa specifies the form of op(a) to be used in the matrix multiplication as follows: 

If transa = 'N' or *n\ op(tf) = a. 
If transa = 'T or V, op(a) = a'. 
If transa = 'C or *c\ op(a) = a'. 

On exit, transa is unchanged. 

diag Type character* 1. 

On entry, diag specifies whether or not a is unit triangular as follows: 

If diag = 'IT or *u\ a is assumed to be unit triangular. 
If diag - *N* or V, a is not assumed to be unit triangular. 

On exit, diag is unchanged. 
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m Type integer. 

On entry, m specifies the number of rows in b. 
Argument m must be at least 0* 
On exit, m is unchanged. 

n Type integer. 

On entry, n specifies the number of columns in b. 
Argument n must be at least 0. 
On exit, n is unchanged. 

alpha Type real 

On entry, alpha specifies the scalar alpha. 

When alpha is 0, a is not referenced, and b need not be set before entry. 
On exit, alpha is unchanged. 

a Type real. 

Array of dimension (Ida, k). 

Argument k is m when side = *L* or T, and is n when side = *R' or V. 

Before entry with uplo - 'IT or V, the leading jfc-by-Jfc upper triangular part of array a must 

contain the upper triangular matrix. 

The strictly lower triangular part of a is not referenced. 

Before entry with uplo = 'L* or T, the leading Jfc-by-it lower triangular part of array a must 

contain the lower triangular matrix. 

The strictly upper triangular part of a is not referenced. 

Note that when diag = *U* or V, the diagonal elements of a are not referenced, but are 
assumed to be unity. 
On exit, a is unchanged. 

Ida Type integer. 

On entry, Ida specifies the first dimension of a as declared in the calling (sub)program. 
When side = 'L' or T, Ida must be at least max(l, m). 
When side = *R' or V, Ida must be at least max(l, n). 
On exit, Ida is unchanged. 

b Type real. 

Array of dimension (Idb, n). 

Before entry, the leading m~by-n part of array b must contain the right-hand side matrix b. 
On exit, b is overwritten by the solution matrix x. 

Idb Type integer. 

On entry, Idb specifies the first dimension of b as declared in the calling (sub)program. 
Argument Idb must be at least max(l, m). 
On exit, Idb is unchanged. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTES 

STRSM is a level 3 Basic Linear Algebra Subprogram (BIAS 3). 
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NAME 

STRSV - Solves a real triangular system of linear equations 
SYNOPSIS 

CALL SJVLSV{uplo t trans4iag t n t a t lda t x t incx) 

DESCRIPTION 

STRSV solves one of the systems of equations 

a*x = b or a'*x = b 

where b and x are n element vectors, and a is an n-by-n unit, or non-unit, upper or lower triangular matrix. 

uplo Character* 1 . On entry, uplo specifies whether matrix is an upper of lower triangular matrix. When 
uplo=*\J* or V, a is an upper triangular matrix. When uplo=V or T, a is a lower triangular 
matrix. The uplo argument is unchanged on exit. 

trans Character* 1. On entry, trans specifies the operation to be performed. If trans=W or *n\ a*x = b. 
If trans^'T or T , a* *x = b. The trans argument is unchanged on exit. 

diag Character*!, On entry, diag specifies whether or not a is unit triangular. If diag^'U* or V, a is 
assumed to be unit triangular. If diag=*N* or 'n\ a is not assumed to be unit triangular. The diag 
argument is unchanged on exit. 

n Integer. On entry, n specifies the order of the matrix a. The n argument must be at least 0. The n 
argument is unchanged on exit 

a Real array of dimension (Idajt). Before entry with uplo=U y or V, the leading n-by-n upper tri- 
angular part of the array a must contain the upper triangular matrix and the strictly lower triangular 
part of a is not referenced. Before entry with uplo^L' or T, the leading n-by-n lower triangular 
part of the array a must contain the lower triangular matrix and the strictly upper triangular part of a 
is not referenced. Note that when diag=U* or V, the diagonal elements of a are not referenced 
either, but are assumed to be unity* The a argument is unchanged on exit. 

Ida Integer. On entry, Ida specifies the first dimension of a as declared in the calling subprogram. 
Argument Ida must be at least max(l ji). The Ida argument is unchanged on exit. 

x Real array of dimension at least 1+ (*-l)*| incx\. Before entry, the incremented array jc must contain 
the n element right-hand side vector 6. On exit, x is overwritten with the solution vector x. 

incx Integer. On entry, incx specifies the increment for the elements of x. Argument incx must not be 0. 
The incx argument is unchanged on exit 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

STRSV is a level 2 Basic Linear Algebra Subprogram (BLAS 2), 
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NAME 

SXMPY - Multiplies a matrix by a row vector and adds the result to another row vector 

SYNOPSIS 

CALL SXMPY(n7 ,ldy,y,n2,ldx,x,ldm l m) 

DESCRIPTION 



nl Number of columns in matrix y (input) 

Idy Leading dimension of matrix y (input) 

y Matrix specifying row vector used in sum and for result (input/output) 

n2 Number of columns in matrix x (input) 

Idx Leading dimension of matrix x (input) 

x Matrix specifying row vector used in product (input) 

Idm Leading dimension of matrix m (input) 

m Matrix used in product (input) 



SXMPY executes an operation equivalent to the following Fortran code: 

SUBROUTINE SXMPY(N1JLDY,Y,N2,LDX,X,LDM > M) 
REAL Y(LDY,1), X(LDX,1), M(LDM,1) 
DO 20 J=1,N2 

DO 20 1=1, Nl 

Y(U)=Y(1,I) + X(U) * M(J,I) 
20 CONTINUE 
RETURN 
END 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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5. FAST FOURIER TRANSFORM ROUTINES 



These routines apply a Fast Fourier Transform. Each routine can compute either a Fourier analysis or a 
Fourier synthesis. Detailed descriptions, algorithms, performance statistics, and examples of two of 
these routines appear in Complex Fast Fourier Transform Binary Radix Subroutine (CFFT2), CRI publi- 
cation SN-0203; and Complex to Real Fast Fourier Transform Binary Radix Subroutine (CRFFT2), CRI 
publication SN-0206, 

CFFT2, RCFFT2, and CRFFT2 have the same argument list: (init,ix,n,x t work t y). 



Parameter 


Description 


inii 


Initialization flag 


ix 


Analysis/Synthesis flag 


n 


Size of transform 


X 


Input vector 


work 


Working storage vector 


y 


Result vector 



The routines are called the first time with initio and n as a power of 2 to initialize the needed sine and 
cosine tables in the working storage area work. Then for each input vector of length n (length (n/2)+l 
for CRFFT2), each routine is called with init^O. The sign of ix determines whether a Fourier synthesis 
or a Fourier analysis is computed: if the sign of ix is negative, a synthesis is computed; if the sign is 
positive, an analysis is computed. 

The following table shows the size and formats of x f y, and work for each routine. 



Arguments for Fast Fourier Transform Routines 


Argument 


CFFT2 


RCFFT2 


CRFFT2 


X 


Complex n 


Real n 


Complex 
(*/2)+l 


work 


Complex 
(5/2)/i 


Complex 
(3/2)n+2 


Complex 
(3/2)n+2 


y 


Complex n 


Complex 
(n/2)+l 


Real n 



CFFTMLT and RFFTMLT apply Fast Fourier Transforms on multiple input vectors. Refer to the docu- 
mentation for each routine for details. 
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The following table contains the purpose, name, and manual entry of each Fast Fourier Transform rou- 
tine. 

The "manual entry" is the name of the manual page containing documentation for the routine listed. 



Fast Fourier Transform Routines 


Purpose 


Name 


Manual Entry 


Apply a complex Fast Fourier Transform 


CFFT2 


CFFT2 


Apply multiple complex-to-complex 
Fast Fourier Transforms 


CFFTMLT 


CFFTMLT 


Apply a complex-to-real Fast Fourier 
Transform 


CRFFT2 


CRFFT2 


Apply a real-to-complex Fast Fourier 
Transform 


RCFFT2 


RCFFT2 


Apply multiple complex-to-real and 
real-to-complex Fast Fourier Transforms 


RFFTMLT 


RFFTMLT 
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NAME 



CFFT2 - Applies a complex Fast Fourier Transform (FFT) 



SYNOPSIS 



CALL CFVr2(init,ix,n t x,work,y) 



DESCRIPTION 



init 



If non-zero, generates sine and cosine tables in work. 

If zero, calculates Fast Fourier Transforms using sine and cosine tables of the previous call. 



x 



n 



ix 



> 0 Calculates a Fourier Analysis 
< 0 Calculates a Fourier Synthesis 

Size of the Fourier transform; T 1 where m > 3 for the CRAY Y-MP, CRAY X-MP, and 
CRAY -2 computer systems, and m £ 2 for the CRAY-1 computer system. 

Input vector of n complex values. 

Range of r. 




Vector x can be equivalenced to the work vector. In this case the input values are 
overwritten. 



work 



Work storage vector of (— )n complex values. 
Complex result vector of size n. 



y 



CFFT2 calculates: 

Vk = S x j exp(±-2-5J- jk) 

for fcs04t-»«n-l; where i 2 = -1. 

The sign of the exponent is the same as the sign of ix. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

CRFFT2(3SCI), RCFFT2(3SCI) 
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NAME 

CFFTMLT - Applies complex-to-complex Fast Fourier Transforms (FFT) on multiple input vectors 
SYNOPSIS 

CALL CFFTMLT(ar>ai,workjrigs t ifaxjncjump,nJotw 
DESCRIPTION 

ar Vector of n*lot real values. 

On input, it contains the real part of the input data. 

On ouput, it contains the real part of the transformed data, 

ai Vector of n*lot real values. 

On input, it contains the imaginary part of the input data. 

On output, it contains the imaginary part of the transformed data. 

work Work storage vector of 4*n*lot real values. 

trigs Input vector of 2*n real values. It must be initialized to contain sine and cosine tables. 
This vector and ifax (following) can be initialized by the following call: 

CALL CFTFAX(/m/<ik, trigs) . 

(CFTFAX returns in ifax{\) an error flag of -99 if n is not factorable as given below.) 

ifax Input vector of at most 19 integer values. It has a previously prepared list of factors of n. 

inc The increment within each data vector. 

jump The increment between the start of each data vector. 

inc and jump apply to both the real and imaginary parts of the data. 
To obtain best performance, jump should be an odd number, 

n Length of the data vectors. 
n must be factorable as: 

n = 2* * 3* * 5 r 

where p> q, and r are integers. 

lot The number of data vectors, 

isign +1 for Fourier analysis 
-1 for Fourier synthesis 

CFFTMLT applies complex-to-complex Fast Fourier transforms on more than one input vector: 

n-l 

{ar(inc*k+l) 1 pi(inc*k+\)) = £ exp{isignHota*2*pi*j*kln)(ar{inc*j+l) r ai(inc*j+\)) 

for k = 0,1 1. 

This calculation is performed for each of the ^-vectors in the input. 
Vectorization is achieved by doing parallel transforms, with vector length = lot. 
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IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

In the division by n, the normalization used by CFFTMLT is different from that used by CFFT2, 
CRFFT2, and RCFFT2. 
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NAME 

CRFFT2 - Applies a complex-to-real Fast Fourier Transform (FFT) 

SYNOPSIS 

CALL CRFFT2(init t ix,n,x,work t y) 

DESCRIPTION 

init If non-zero, generates sine and cosine tables in work. 

If zero, calculates Fast Fourier Transforms using sine and cosine tables of the previous call. 

ix > 0 Calculates a Fourier Analysis 
< 0 Calculates a Fourier Synthesis 

n Size of the Fourier transform; 2 m where m £ 3 

x Input vector of complex values. 

« 10 2466 
Range of xr. iq2466 < | x< | £ — - — for / = 1,2,...,*, 

3 

work Work storage vector of (— )«+2 complex values. 
j> Real result vector of n values. 

CRFFT2 calculates the following equation: 

for k=0,l f ...ji-l 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

xj elements are complex and related by xj = x n ^ for j = l^,...,^). 
Only the first (-^M elements are stored in x. 

SEE ALSO 

CFFT2(3Sa). RCFFT2(3SCI) 
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NAME 

RCFFT2 - Applies a rcal-to-complcx Fast Fourier Transform (FFT) 

SYNOPSIS 

CALL RCFFT2(init,ix,njc,work t y) 

DESCRIPTION 

init If non-zero, generates sine and cosine tables in work. 

If zero, calculates Fast Fourier Transforms using sine and cosine tables of the previous call. 

ix > 0 Calculates a Fourier Analysis 
< 0 Calculates a Fourier Synthesis 

n Size of the Fourier transform; 2 m where m > 3. 

x Input vector of n real values. 
Range of r. 

^ J ^ I £ — r — for * = 1,2,...,*. 



10 2466 ' 11 2n 

3 

warjfc Work storage vector of +2 complex values, 
y Complex result vector of (-y ) + 1 values. 



RCFFT2 calculates: 

yk=2 n £x i cxp(±^jk) 



for WU..... (-|) 

The sign of the exponent is the same as the sign of ix. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

CFFT2(3SCI), CRFFT2(3SCI) 
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NAME 

RFFTMLT - Applies complex-to-real and real-to-complex Fast Fourier Transforms (FFT) on multiple 
input vectors 

SYNOPSIS 

CALL RFFTMhT(a t workjrigsJfaxMcjurnp > nJot t isign) 
DESCRIPTION 

a When isign = -1, the n real input values for each data vector: 
a(l), a(l+inc) f a(2*//ic+l), ■ ■ ■ , a((n-l)*inc+l) 
should be stored in vector a with stride = inc. 

The computed output vector is: 

a(2*wc*f+l), a(2*i»c*(/+l>H). " " " for i = 1,2,.-.. -j. 

The i-th Fourier coefficient is: 
(a(2*mc*i+l), a(2*wc* (i+l)+l)). 

When iwgfl = +1, the input and output data formats are reversed. 

It is important to note that for / = I and i ' = ^ the imaginary parts of the complex input 
numbers must be 0. 
work Work storage vector of size 2*n*lot real values. 

trigs Input vector of 2*n real values. It must be initialized to contain sine and cosine tables. Vectors 
trigs and ifax (following) can be initialized by the following call: 

CALL FFTFAX(/i t ifax t trigs). 

(FFTFAX returns in infax(l) an error flag of -99 if n is not factorable as given below,) 
ifax Input vector of at most 19 integer elements. It has a previously prepared list of factors of n. 
inc The increment within each data vector. 

jump The increment between the start of each data vector, inc and jump apply to both real and ima- 
ginary data. For the best performance, jump should be an odd number, 

n Length of the data vectors. 

n must be even and factorable as: 

n = 2 p * 3* * 5 r 

where p f q 9 and r are integers. 

lot The number of data vectors 

isign -1 to calculate real-to-complex Fourier transform 
+ 1 to calculate complex-to-real Fourier transform 
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RFFTMLT applies complex-to-real and real-to-complex Fast Fourier transforms on more than one input 
vector. 

For isign = -1, RFFTMLT calculates the following: 

(ar(inc*k+l)*ai(inc*k+l)) = £ exp(-iota*2*pi*j*kln)*a(inc*j+l)ln 

J=o 

fork = 0,1,..., -j. 

iota is the square root of -1. 

The numbers on the left side of the equation are complex. 
This calculation is performed for each of the n-vectors in the input. 

For isign - +1, RFFTMLT calculates the following: 
»-i 

a(mc*i+l) - £ exp (iota* 2*piy*kfn)* (a(2*inc*j+l)/i(2*incy+inc+l)) 

for k = 0,1,...,*. 

iota is the square root of -1. 

This calculation is performed for each of the n- vectors in the input. 

Each input vector satisfies the relationship: 
a (2*k*inc +1) = a (2* (n ~k)*inc +1) 
a(2*(*+l)*mc+l) = -fl((2*(/t-ifc)+l)*mc+l) 

for k = 0,1,..., ~. 

Only the first complex values are needed. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

NOTES 

RFFTMLT uses a normalization different from the one used by CFFT2, CRFFT2, and RCFFT2. 
Vectorization is achieved by doing parallel transforms, with vector length = lot. 
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6. SEARCH ROUTINES 



The following search routines are written to run optimally on Cray computer systems. These subpro- 
grams use the call-by-address convention when called by a Fortran or CAL program. 

The subprograms are grouped as follows: 

• Maximum/minimum element search routines 

• Vector search routines 

Maximum/Minimum Element Search Routines 

The maximum and minimum element search routines find the largest or smallest element of a vector or 
argument and return either the element or its index. 

To return an index - ISMAX and ISMIN return the index of the maximum or minimum vector element, 
respectively. ISAMAX, ICAMAX, and ISAMIN search for maximum or minimum absolute values in a 
real vector and return the index. INTMAX and INTMIN are the corresponding maximum and minimum 
search routines for an integer vector. INFLMAX and INFLMIN return the index of the maximum and 
minimum value within a table. The type declaration for these routines is integer. For further details 
regarding type and dimension declarations for variables occurring in these subprograms, see section 4, 
Linear Algebra Subprograms. 

To return an element - The following functions find the maximum or minimum elements of two or 
more vector arguments: MAXO, AMAX1, DMAX1, AMAXO, MAX1, MINO, AMIN1, DMIN1, AMINO, and 
MINI. These functions differ mainly in their types for integer, real, and double-precision arguments. 
In the description of these functions, the argument type does not always reflect the function type. 
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The following table contains the purpose, name, and manual entry of each maximum/minimum element 
search routine. 

The "manual entry" is the name of the manual page containing documentation for the routine(s) listed. 



Maximum/Minimum Element Search Routines 


Purpose 


Name 


Manual Entry 


Find the first index of the largest 
absolute value of the elements of a 
real or complex vector 


ISAMAX 
ICAMAX 


ISAMAX 


Return the index of the maximum value 
in a table 


INFLMAX 


INFLMAX 


Return the index of the minimum value 
in a table 


INFLMIN 


Return the index of the integer vector 
element with maximum value 


INTMAX 


INTMAX 


Return the index of the integer vector 
element with minimum value 


INTMIN 


Return the index of the vector element 
with maximum value 


ISMAX 




Return the index of the vector element 
with minimum value 


ISMIN 


ISMAX 


Return the index of the vector element 
with minimum absolute value 


ISAMIN 




Return the largest of all arguments 


MAXO 

AMAXl 

DMAXl 

AMAXO 

MAXl 


MAX 


Return the smallest of all arguments 


MINO 

AMINl 

DMINl 

AMINO 

MINI 


MIN 



Vector Search Routines 

Vector search routines have one of the following functions: 

• To return occurrences of an object in a vector 

• To search for an object in a vector 

To return occurrences of an object in a vector - These integer routines return the number of 
occurrences of a given relation in a vector. The routines 1LLZ and IILZ find the first occurrence. 
ILSUM counts the number of such occurrences. All three of these functions are described under the 
heading IILZ. 
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To search for an object in a vector - ISRCH routines find the positions of an object in a vector. These 
include the following: ISRCHEQ, ISRCHNE, ISRCHFLT, ISRCHFLE, ISRCHFGT, ISRCHFGE, 
ISRCHILT, ISRCHILE, ISRCHIGT, ISRCHIGE, ISRCHMEQ, ISRCHMNE, ISRCHMLT, ISRCHMLE, 
ISRCHMGT, and ISRCHMGE. These functions return the first location in an array that has a true rela- 
tional value to the target 

The WHEN routines are similar to the ISRCH routines in that they return the locations of elements in an 
array that have a true relational value to the target. However, all locations are returned in an indexed 
array. Hie WHEN routines are WHENEQ, WHENNE, WHENFLT, WHENFLE, WHENFGT, WHENFGE, 
WHENILT, WHENILE, WHENIGT, WHENIGE, WHENME, WHENNE, WHENMLT, WHENMLE, 
WHENMGT and, WHENMGE. 

The CLUS routines find the index of clusters that have a true relational value to the target. These rou- 
tines are further divided into integer (CLUSILT, CLUSILE, CLUSIGT, CLUSIGT) and real (CLUSFLT, 
CLUSFLE, CLUSFGT, and CLUSFGE) routines. 

The OSRCHI and OSRCHF subroutines return the index of the location that would contain the target in 
an ordered array. This is useful for sorting elements into a new array. Searching always begins at the 
lowest value in the ordered army. The total number of occurrences of the target in the array can also 
be returned. The OSRCHM routine returns the index of the first location equal to an integer target in an 
ordered integer array. (OSRCHM is available only to COS users.) 

The following table contains the purpose, name, and manual entry of each vector search routine. 
The "manual entry" is the name of the manual page containing documentation for the routine(s) listed. 



Vector Search Routines 


Purpose 


Name 


Manual Entry 


Return the number of occurrences of an 
object in a vector 


IILZ 
ILLZ 
ILSUM 


IILZ 


Find the index of clusters equal or 
not equal to the target 


CLUSEQ 
CLUSNE 


CLUSEQ 


Find the index of clusters of real elements 
that are less than, less than or 
equal to, greater than, or greater 
than or equal to the target 


CLUSFLT 
CLUSFLE 
CLUSFGT 
CLUSFGE 


CLUSFLT 


Find the index of clusters of integer elements 
that are less than, less than or 
equal to, greater than, or greater 
than or equal to the target 


CLUSILT 
CLUSILE 
CLUSIGT 
CLUSIGE 


CLUSILT 


Find the first array element that 
is equal or not equal to the target 


ISRCHEQ 
ISRCHNE 


ISRCHEQ 


Find the first real array element 
that is less than, less than or 
equal to, greater than, or greater 
than or equal to the real target 


ISRCHFLT 
ISRCHFLE 
ISRCHFGT 
ISRCHFGE 


ISRCHFLT 


Find the first integer array element 
that is less than, less than or 
equal to, greater than, or greater 
than or equal to the integer target 


ISRCHILT 
ISRCHILE 
ISRCHIGT 
ISRCHIGE 


ISRCHILT 



SR-0113 



6-3 



D 



INTRO (3X) 



Vector Search Routines (continued) 


Purpose 


Name 


Manual Entry 


Find the first array element that 
is equal or not equal to the target 
within a field 


ISRCHMEQ 
ISRCHMNE 


ISRCHMEQ 


Find the first array element 
that is less than, less than or 
equal to, greater than, or greater 
than or equal to the target within a 
field 


ISRCHMLT 
ISRCHMLE 
ISRCHMGT 
ISRCHMGE 


ISRCHMLT 


Search an ordered integer or real 
array and return the index of the 
first location that contains the 
target 


OSRCHI 
OSRCHF 


OSRCHI 


Search an ordered integer array 
and return index of the first location 
that is equal to the integer target 
(COS only) 


OSRCHM 


OSRCHM 


Find all array elements that are 
equal or not equal to the target 


WHENEQ 
WHENNE 


WHENEQ 


Find all real array elements that 
are less than, less than or equal to, 
greater than, or greater than or 
equal to the real target 


WHENFLT 
WHENFLE 
WHENFGT 
WHENFGE 


WHENFLT 


Find all integer array elements that 
are less than, less than or equal to, 
greater than, or greater than or 
equal to the integer target 


WHENILT 
WHENILE 
WHENIGT 
WHENIGE 


WHENILT 


Find all array elements that are 
equal or not equal to the target 
within a field 


WHENMEQ 
WHENNME 


WHENMEQ 


Find all array elements that 
are less than, less than or equal to, 
greater than, or greater than or 
equal to the target within a field 


WHENMLT 
WHENMLE 
WHENMGT 
WHENMGE 


WHENMLT 
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NAME 

CLUSEQ, CLUSNE - Finds index of clusters within a vector 
SYNOPSIS 

CALL CLUSEQfa, array ,inc,target,index,nn) 
CALL CLVSNE(n>array,inc, target, index \nn) 
DESCRIPTION 



n 


Number of elements to be searched; length of the array. Type integer. 


array 


Real or integer vector to be searched 


inc 


Increment between elements of the searched array. Type integer. 


target 


Scalar to match logically* Type integer or real. 


index 


Indexes in array where the cluster starts and stops (one based); index should be dimen- 




sioned INDEX(2 f */2). 


nn 


Number of matches found; length of index. Type integer. 



These routines find the index of clusters of occurrences equal to or not equal to a scalar within a vector. 
The Fortran equivalent of the type of logical search performed for CLUSEQ and CLUSNE follows: 

ARRAY(IJ=INDEX(1 J),INDEX(2 J) J=l ,NN).EQ.TARGET 

ARRAY(I,I=INDEX(1 J) JNDEX(2,J) J= 1 ,NN) .NE .TARGET 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Searching for the cluster allows vectorization. Before using these routines, you should know that the 
logical search results in clusters of finds. 
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CLUSFLT(3SCI) 



NAME 

CLUSFLT, CLUSFLE, CLUSFGT, CLUSFGE - Finds real clusters in a vector 
SYNOPSIS 

CALL C\jVS¥LT(n&rrayMc target index,nn) 
CALL ClAJSFLE(n&rray >inc, target 4ndex,nn) 
CALL CL\JSFGT(n t array t inc t targ€tMdex t nn) 
CALL CL\}STGJL(n&rray t inc t target t index,nn) 
DESCRIPTION 

n Number of elements to be searched; length of the array. Type integer. 

array Real vector to be searched, 

inc Increment between elements of the searched array. Type integer. 

target Scalar to match logically. Type real. 

index Indexes in array in which the cluster starts and stops (1 based); index should be dimen- 
sioned INDEX(2^i/2). 

nn Number of matches found; length of index. Type integer. 

These routines find the index of clusters of real occurrences in relation to a scalar within a vector. 
The Fortran equivalent of the type of logical search performed by each respective routine follows: 

ARRAY(IJ=INr)EX(l,r),INDEX(2 >NN).LT.TARGET 

ARRAY(I J-INDEX(1 J},INDEX(2 J) J=l ,NN).LE,TARGET 

AIOlAYaJ=INDEX(lJ) > INDEX(2J) t J=l,NN).GT.TARGET 

ARR AY(I J=INDEX(U) JNDEX(1 J) J=l JSN).GE. TARGET 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

Searching for the cluster allows vectorization. Before using these routines, you should know that the 
logical search results in clusters of finds. 
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NAME 

CLUSILT, CLUSBLE, CLUSIGT, CLUSIGE - Finds integer clusters in a vector 
SYNOPSIS 

CALL CLVSlLT(n,iarray,inc>itarget t index t nn) 
CALL CLVSILE(n t iarray,inc,itarget,index t nn) 
CALL CLUSIGT(nMrray4ncMrget4ndex t nn) 
CALL CLUSIGE(rt,iarroy t inc,itarget,index,nn) 
DESCRIPTION 

n Number of elements to be searched; length of the array. Type integer. 

iarray Integer vector to be searched. 

inc Increment between elements of the searched array. Type integer. 

itarget Scalar to match logically. Type integer. 

index Indexes in iarray in which the cluster starts and stops (1 based), index should be dimen- 
sioned INDEX(2,/?/2). 

nn Number of matches found; length of index. Type integer. 

These routines find the index of clusters of integer occurrences in relation to a scalar within a vector. 
The Fortran equivalent of the type of logical search performed by each respective routine follows: 

IARRAYa>INDEX(lJ)J>roEX 

IARRAY(U=INDEX(U)JD^ 

IARRAY(IJ=INDEX(lJ),nsIDEX(2J)J=lJ^.GT.ITARGET 
IARRAY(I,I=INDEX(1 ,J)JNDEX<2 J)J=1 »NN).GE.ITARGET 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTE 

Searching for the cluster allows vectorization. Before using these routines, you should know that the 
logical search will result in clusters of finds. 
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NAME 

ULZ f ILLZ, ILSUM - Returns number of occurrences of object in a vector 

SYNOPSIS 

kount = KLZ(n/irray t incl) 

kount = ILLZ(n f array t incl) 
kount - ILSUM(n, array ,incl) 
DESCRIPTION 

n Number of elements to process in the vector (n=vector length if mc/=l; ^-vector length/2 if 

incl-2, and so on) 

array Vector operand 

incl Increment between elements of the vector operand. For contiguous elements, tnd=l. 

IDLZ returns the number of zero values in a vector before the first nonzero value. 

ILLZ returns the number of leading elements of a vector that do not have the sign bit set, 

ILSUM returns the number of TRUE values in a vector declared logical. 

When scanning backward {incl < 0), both 1ILZ and ILLZ start at the end of the vector and move back- 
ward <L(N),L(N + INCL),L(N + 2*INCL),...). 

If array is of type logical, HLZ returns the number of FALSE values before encountering the first TRUE 
value. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

INFLMAX, INFLMIN - Searches for the maximum or minimum value in a table 

SYNOPSIS 

index=JNFLMAX(n r ixMc,mask t shift) 

indejc=lH FLMIN(/i ,ix4nc,mask t shift) 
DESCRIPTION 

index Index in ix where maximum or minimum occurs (one based). Type integer. 

n Number of elements to be searched; length of the array. Type integer, 

ix Table to be searched. Type integer. 

inc Skip distance through ix. Type integer. 

mask Right-justified mask used for masking the table vector 

shift Number of bits to right shift the table vector before masking 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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INTMAX(3SCI) 



NAME 

INTMAX, INTMIN - Searches for the maximum or minimum value in an integer vector 

SYNOPSIS 

index = INTNLAX(njxMc) 

index = INTMINOuXwc) 

DESCRIPTION 

index Index in ix where maximum or minimum occurs (one based) 
ft Number of elements to be searched; length of the array 

ix Integer vector to be searched 

inc Increment between elements of ix 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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ISAMAX(3SCI) 



NAME 

ISAMAX, ICAMAX - Finds first index of largest absolute value in vectors 

SYNOPSIS 

imax - ISAMAX(n jxjncx) 

imax = lCAMAX(n t cx t incx) 
DESCRIPTION 

n Number of elements to process in the vector to be searched 

(n = vector length if incx = 1; n ~ vector length/2 if incx = 2, and so on). 
If n < 0, ISAMAX and ICAMAX return 0. 

sx Real vector to be searched 

cx Complex vector to be searched 

incx Increment between elements of sx or cx; for contiguous elements, incx = 1. 

These integer functions find the first index of the largest absolute value of the elements of a vector. 

ISAMAX returns the first index / such that 

\xi | = max | xj \:j = l, wmm /i 
where xj is an element of a real vector. 
ICAMAX determines the first index i such that 

| Reat(Xi) | + 1 Imag(xi) | = max | Real{xj) \ + | Imag(x } ) \ : j = 1, . . . t n 
where Xj is an element of a complex vector. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

ISMAX, ISMIN, ISAMIN - Finds maximum, minimum, or minimum absolute value 

SYNOPSIS 

imax = I$MAX(n t sx>incx) 

imin = lSMtN(n,sx,incx) 

imin - ISAMIN(n,sx,i/icx) 

DESCRIPTION 

n Number of elements to process in the vector to be searched 

(n = vector length if incx = 1; n = vector length/2 if incx = 2; and so on). 
If n < 0, ISMAX, ISMIN, and ISAMIN return 0. 

sx Real vector to be searched 

incx Increment between elements of sx. For contiguous elements, incx = 1. 

These routines return the index of the element with maximum, minimum, or minimum absolute value. 

ISMAX returns the first index i such that 

1*1 = max xj :j = 
where Xj is an element of a real vector, 
ISMIN and ISAMIN return the first index i such that 

\xi\- min xj :j - l,...,n 
where xj is an element of a real vector. 
ISMAX, ISMIN, and ISAMIN are integer functions. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 



ISRCHEQ, ISRCHNE - Finds array element equal or not equal to target 



SYNOPSIS 



location 



lSRCUEQin,array,inc,target) 



location 



ISRCHSE(n.arrayjnc,target) 



DESCRIPTION 



inc 



target 



n 



array 



Number of elements to be searched. If n £ 0, 0 is returned. 

First element of the real or integer array to be searched 

Increment between elements of the searched array 

Real or integer value searched for in the array. 
If target is not found, the returned value is n+1. 



ISRCHEQ finds the first real or integer array element that is equal to a real or integer target. 
ISRCHNE returns the first location for which the relational value not equal to is true for real and integer 



The Fortran equivalent code for ISRCHEQ is as follows: 



FUNCTION ISRCHEQ(N,ARRAY,INC,TARGET) 

DIMENSION ARRAY(l) 

J=l 

ISRCHEO=0 

IF(N1E.0) RETURN 

IFONGLT.0) J=1-(N-1)*INC 

DO 100I=1JN 

IF(ARRAY(J).EQ.TARGET) GO TO 200 
J=J+INC 
100 CONTINUE 
200 ISRCHEQ=I 

RETURN 

END 



IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 



ISRCHEQ replaces the ISEARCH routine, but it has an entry point of ISEARCH as well as ISRCHEQ. 



arrays. 



NOTES 
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NAME 



ISRCHFLT, ISRCHFLE, ISRCHFGT, ISRCHFGE - Finds first real array element in relation to a real 
target 



SYNOPSIS 

location 

location 
location 
location 
DESCRIPTION 
n 

array 

inc 

target 



lSRCHFLT(n t array,inc,target) 
ISRCKFLE(n t arrayMc,target) 
ISRCHFGT(n,arrayjncjarget) 
ISRCfflGE(n,array,inc t target) 



Number of elements to be searched. If n £0, 0 is returned. 

First element of the real array to be searched 

Increment between elements of the searched array 

Real value searched for in array. 

If target is not found, the returned value is n+l. 



These functions return the first location for which the relational operator is true for real arrays. 
ISRCHFLT finds the first real array element that is less than the real target. 
ISRCHFLE finds the first real array element that is less than or equal to the real target. 
ISRCHFGT finds the first real array element that is greater than the real target. 
ISRCHFGE finds the first real array element that is greater than or equal to the real target. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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ISRCHILT(3SCI) 



NAME 



ISRCHILT, ISRCHILE, ISRCHIGT, ISRCHIGE - Finds first integer array element in relation to an 
integer target 



SYNOPSIS 

location 

location 
location 
location 
DESCRIPTION 
n 

iarray 
inc 

itarget 



lSRCmUT(n 9 iarr ay jnc, itarget) 
l$RCmLE(n,iarrayjnc,itarget) 
ISRCmGT(n,iarray t incJtarget) 
ISRCHLGE(n,iarray t inc, itarget) 



Number of elements to be searched. If n £0, 0 is returned. 

First element of the integer array to be searched 

Increment between elements of the searched array 

Integer value searched for in iarray. 

If target is not found, the returned value is 



These functions return the first location for which the relational operator is true for integer arrays, 

ISRCHILT finds the first integer array element that is less than the integer target 
ISRCHILE finds the first integer array element that is less than or equal to the integer target. 
ISRCHIGT finds die first integer array element that is greater than the integer target 
ISRCHIGE finds the first integer array element that is greater than or equal to the integer target. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

ISRCHMEQ, ISRCHMNE - Finds the index of the first occurrence equal or not equal to a scalar within 
a field of a vector 

SYNOPSIS 

index = ISRCHMEQ(rt, array ,inc, target t mask .right) 
index - ISRCHMNE(n t array,inc t target t mask,right) 
DESCRIPTION 

index Index in array where first logical match with the target occurred (one based); index=n+l if 
match is not found. Type integer. 

n Number of elements to be searched; length of the array. Type integer. 

array Real or integer vector to be searched 

inc Increment between elements of the searched array. Type integer. 

target Scalar to match logically- Type integer or real. 

mask Mask of l's from the right; the size of the field looked for in the table. 

right Number of bits to shift right so as to right-justify the field searched. Type integer. 

The Fortran equivalent of ISRCHMEQ and ISRCHMNE follows: 
TABLE(ARRAY(INDEX(I),I=l t NN))£Q.TARGET 
TABLE( ARRAY(INDEX(I) J= 1 ,NN))-NE.TARGET 
where TABLE(X)=AND(MASK,SHIFTR(XJRIGHT)) 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

ISRCHMLT, ISRCHMLE, ISRCHMCT, ISRCHMGE - Searches vector for logical match 
SYNOPSIS 

index = ISRCHMLTfoarray^/ic, target jnaskjight) 
index = I$RCHMLE(n t anayMcjargetjruisk t right) 
index = ISRCHMGT(n,array,inc t target t mask t right) 
index = \SRCHMGE(n>arrayjncjarget t masksight) 
DESCRIPTION 

index Index in array where first logical match with the target occurred (one based); index=n+l if 
match is not found. Type integer, 

n Number of elements to be searched; length of the array. Type integer. 

array Real or integer vector to be searched 

inc Increment between elements of the searched array. Type integer. 

target Scalar to match logically. Type integer or real. 

mask Mask of Vs from the right; the size of the field looked for in the table 

right Number of bits to shift right so as to right justify the field searched. Type integer. 

These routines search an array, returning the index of the first element that creates a logical match with 
the target. 

ISRCHMLT searches for an element less than the target 
ISRCHMLE searches for an element less than or equal to the target 
ISRCHMGT searches for an element greater than the target. 
ISRCHMGE searches for an element greater than or equal to the target 

The Fortran equivalent of each logical search performed follows: 

TABLE(ARR AY(INDEX(I)J= 1 JNN))iT.TARGET 

TABLE(ARRAY(INDEX(I),I= 1 J^N))JLE.TARGET 

TABLE(ARR A Y(INDEX(I),I=1 t NN)).GT.TARGET 

TABLE(ARRAY(INDEX(I),I= 1 ,NN)).GE .TARGET 

where TABl^(X)=AND(MASK,SHIFTR(X^IGHT)) 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

MAXO, AMAX1, DMAX1, AMAXO, MAX1 - Returns the largest of all arguments 

SYNOPSIS 

/ = MAXO (integer integer 2 ,„. 9 integer n ) 
r = AMAXl(reatifeal2>.»* reat n ) 
d = VMAXl(double u doubte 2 ,..., double*) 
r = AMAXO(integer u integer 2f ...> integer*) 
i - MAXl(realifeal2>—, real n ) 

DESCRIPTION 

MAXO, AMAX1, and DMAX1 use integer, real, and double-precision arguments, respectively, and return 
the same type of result. Each function is of the same type as its arguments. 

AMAXO (type real) returns a real result from integer arguments. 

MAX1 (type integer) returns an integer result from real arguments. 

All of the arguments within each function must be of the same type, and the number of arguments n 
must be in the range 2 < n < 64. Arguments must be in the range | x \ < <» 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

MAX is the generic name for the maximum routines MAXO, AMAX1, and DMAX1. Calls to 

i - MAX(integer u integer 2 ,..Jnteger fl ) 

r = lAAX(recdijreal 2 *..>feal n ) 

d = MAX(double ^double 2 ^4ouble n ) 

will return integer, real, and double-precision results, respectively. 
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NAME 

MINO, AMIN1, DMIN1, AMINO, MINI - Returns the smallest of all arguments 

SYNOPSIS 

i - MrN0(integer 1 ,integer 2 ,...> integer*) 
r = AMINl(reafi l rea/2,..., real*) 
d = \>WNl(double Rouble 2*...* double*) 
r - AMlNO(integer integer 2^ integer*) 
i = MINl(real u real 2,...,real*) 

DESCRIPTION 

MINO, AMINl, and DMEV1 use integer, real, and double-precision arguments, respectively, and return 
the same type of result. Each of these functions is of the same type as its arguments. 

AMINO (type real) returns a real result from integer arguments. 

MINI (type integer) returns an integer result from real arguments. 

All of the arguments within each function must be of the same type. 
The number of arguments n must be in the range 2 ^ n < 64. 
Arguments must be in the range [ x | < <» . 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

MIN is the generic name for the minimum routines MINO, AMINl, and DMIN1. Calls to 

i - MIN(integer u integer 2 ,*.Jnteger n ) 

r = MJN(real u real 2>...feal n ) 

d = MJN(daublei4ouble2f^4ouble m ) 

will return integer, real, and double-precision results, respectively. 
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NAME 

OSRCHI, OSRCHF - Searches an ordered array and returns index of the first location that contains the 
target 

SYNOPSIS 

CALL OSRCHl(nMrrayMcMrgetMdex4whereMum) 

CALL OSRCHF(n^rrayJnc t targ€tMdex t iwhere t inum) 

DESCRIPTION 

n Number of elements of the array to be searched 

iarray Beginning address of the integer array to be searched 
array Beginning address of the real array to be searched 

inc A positive increment indicates an ascending array and returns the index of the first element 

encountered, starting at the beginning of the array. 

A negative increment indicates a descending array and returns the index of the last element 
encountered, starting at the beginning of the array. 

target Integer or real target of the search 

index Index of the first location in the searched array that contains the target; exceptional cases 
are as follows: 

If n < 1, index = 0 

If no equal array elements, index = n+1 

iwhere Index of the first location in the searched array that would contain the target if it were 
found in the array. If the target is found, index = iwhere. There is one exceptional case; if 
n is less than 1, iwhere = 0, 

inum Number of target elements found in the array 

OSRCHI searches an ordered integer array and returns the index of the first location that contains the 
target (type integer). 

OSRCHF searches an ordered real array and returns the index of the first location that contains the tar- 
get (type real). 

Searching always begins at the lowest value in the ordered array. Even if the target is not found, the 
index of the location that would contain the target is returned. The total number of occurrences of the 
target in the array (inum) can also be returned. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

OSRCHM - Searches an ordered integer array and returns index of the first location that is equal to the 
integer target 

SYNOPSIS 

CALL 0$RCK\l(nterrayMcMarget t mask,shift,index4w 

DESCRIPTION 

n Number of elements of the array to be searched 

iarray Beginning address of the integer array to be searched 

inc Increment between elements of the array to be searched. Argument inc should be 1 for 

contiguous elements of memory. Argument inc should be -1 to find the last element with a 
true condition, 

A positive increment indicates an ascending array. A negative increment indicates a des- 
cending array. 

itarget Integer target of the search 

mask Mask set from the right side of the field of interest in vector iarray 

shift Amount to right-shift vector iarray to position the field of interest at right side of word 

index Index of the first location in the searched array where the target is equal to an element of 
that array; exceptional cases are as follows: 

If n < 1, index = 0 

If no equal array elements, index = n+1 

iwhere Index of the first location in the searched array where the target would fit and maintain the 
order of the array. If the target is found, index = iwhere. There is one exceptional case; 
if n < 1, index - 0. 

inum On input, must be non-zero if the number of array elements equal to the target is desired. 

On output, number of elements found in the array equal to the target This will return a 
value only if asked for and at least 1 target value is found in the array. Otherwise, it will 
always be 0. 



OSRCHM searches an ordered integer array and returns the index of the first location that is equal to 
the integer target It also returns the index of where the target should fit into the array, whether it finds 
a value equal to the target or not Optionally, it will find the total number of array elements equal to 
the target 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 



WHENEQ, WHENNE - Finds all array elements equal to or not equal to the target 



SYNOPSIS 



CALL yVBESEQ(n,array,inc t target t index t nval) 



CALL 1 WUESSE(n > array l inc t target l index f nva[) 



DESCRIPTION 



n 



Number of elements to be searched 



target 
index 



array 
inc 



First element of the real or integer array to be searched 

Increment between elements of the searched array 

Real or integer value searched for in the array 

Integer array containing the index of the found target in the array 

Number of values put in the index array 



WHENEQ finds all real or integer array elements that are equal to a real or integer target. 

WHENNE returns all locations for which the relational value not equal to is true for real and integer 
arrays. 

The Fortran equivalent follows: 

INA=1 
NVAL=0 

IF(INC IT. 0) INA=(-INC)*(N-1)+1 
DO 100 1=1 ,N 

IF(ARRAY(INA) ,EQ. TARGET) THEN 
NVAL=NVAL+1 
INDEX(NVALH 
END IF 
INA=INA+INC 
100 CONTINUE 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

WHENFLT, WHENFLE, WHENFGT, WHENFGE - Finds all real array elements in relation to the real 
target 

SYNOPSIS 

CALL WHENFLT(n,array,inc, target t index,nval) 

CALL WHENELE(n f arrayjnc,target t index t nval) 

CALL WHENFGT(n,array t inc t target t index t nvar) 

CALL VtnEHFGEfaarrayMcjargetjndeXtnval) 

DESCRIPTION 

n Number of elements to be searched 

array First element of the real array to be searched 

inc Increment between elements of the searched array 

target Real value searched for in the array 

index Integer array containing the index of the found target in the array 

nval Number of values put in the index array 

These functions return all locations for which the relational operator is true for real arrays. 

WHENFLT finds all real array elements that are less than the real target. 
WHENFLE finds all real array elements that are less than or equal to the real target 
WHENFGT finds all real array elements that are greater than the real target. 
WHENFGE finds all real array elements that are greater than or equal to the real target. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

WHENILT, WHENILE, WHENIGT, WHENIGE - Finds all integer array elements in relation to the 
integer target 

SYNOPSIS 

CALL WKENUJT(n t iarray f incMarget t index t nval) 

CALL y/HENiLE(n4array f inc f itarget,index T nval) 

CALL \VHEMGT(nMrray t inc t itarget>index.nvat) 

CALL y^^E^lGE{n t iarray t mc t itargetSndex,nval) 

DESCRIPTION 

n Number of elements to be searched 

iarray First element of the integer array to be searched 

inc Increment between elements of the searched array 

itarget Integer value searched for in the array 

index Integer array containing the index of the found target in the array 

nval Number of values put in the index array 

These functions return all locations for which the relational operator is true for integer arrays. 

WHENILT finds all integer array elements that are less than the integer target, 
WHENILE finds all integer array elements that are less than or equal to the integer target, 
WHENIGT finds all integer array elements that are greater than the integer target. 
WHENIGE finds all integer array elements that are greater than or equal to the integer target. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

WHENMEQ, WHENMNE - Finds the index of occurrences equal or not equal to a scalar within a field 
in a vector 

SYNOPSIS 

CALL WHENMEQ(n,arr(^4nc f target l index 9 nn t rruisk f righO 
CALL WHENMNE(n,array4ncjargetjndex.nn,mask l right) 

DESCRIPTION 



n 


Number of elements to be searched; length of the array 


array 


Vector to be searched 


inc 


Increment between elements of the searched array 


target 


Scalar to match logically 


index 


Indexes in array where all logical matches with the target occurred (one based) 


nn 


Number of matches found. Length of index. 


mask 


Mask of Ts from the right; the size of the field looked for in the table 


right 


Number of bits to shift right so as to right-justify the field searched 



The Fortran equivalent of WHENMEQ and WHENMNE follows: 
TABLE(ARRAY(INDEX(I),I=1 ,NN)).EQ.TARGET 
TABLE(ARRAY(INDEX(1),I= 1 > NN)).NE.TARGET 
where TABLE(X)=AND(MASK,SHIFTR(X^IGHT)) 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

WHENMLT, WHENMLE, WHENMGT, WHENMGE - Finds the index of occurrences in relation to a 
scalar within a field in a vector 

SYNOPSIS 

CALL WHENMLTfn^rroy^'nCpfar^^m^JC^n^o^^r/^A/) 
CALL WHE^MLE(n,arrayMc t targetMdex,nn t mask,right) 
CALL \^HEl^GT{nArrayincMrg€tMdexm f fnasknght) 
CALL WHENMGE(n f arrayMc,target t index,nn,mask t right) 
DESCRIPTION 

n Number of elements to be searched; length of the array 

array Vector to be searched 

inc Increment between elements of the searched array 

target Scalar to match logically 

index Indexes in array where all logical matches with the target occurred (one based) 
nn Number of matches found. Length of index. 

mask Mask of l's from the right; the size of the field looked for in the table 
right Number of bits to shift right so as to right-justify the field searched 

The Fortran equivalent of logical search performed follows: 

TABLE(ARRAY(INDEXa) > I=lW)-LT.TARGET 
TABLE(ARRAY(INDEX(I) t I=lJ^N))iETARGET 
TABLE(ARRAY(INDEX(I),1=IJ S JN)).GT.TARGET 
TABLE(ARRAY(INDEX(I)J-1 ,NN))-GE.TARGET 
where TABLE(X)=AND(MASK > SHIFTR(XJIIGHT)) 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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7. SORTING ROUTINES 



There are two ways to perform a sort on files: they can be sorted using the SORT control statement or 
the SORT subroutines. The ORDERS routine is used to sort memory arrays rather than files. 

The SORT control statement provides a generalized sort and merge capability. SORT accesses multiple 
input files and permits mixed key types and variable length records. It provides a variety of user- 
specified random access devices (such as disk, Buffer Memory Resident (BMR), and SSD solid-state 
storage device) and tuning parameters for performance enhancement 

The SORT program provides these capabilities through calls to the SORT subroutines. SORT subroutines 
provide all of the above-mentioned options and allow the use of user-supplied subroutines. For more 
information on SORT and its associated subroutines, see the SORT Reference Manual, CRI publication 
SR-0074, 

ORDERS is an internal, fixed-length record sort optimized for Cray computer systems. This section 
gives the synopsis and description of the ORDERS routine, including several examples using ORDERS. 
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NAME 

ORDERS - Sorts using internal, fixed-length record sort optimized for Cray computer systems 
SYNOPSIS 

CALL ORDERS(mo(tejwork,dataMdex,n4reclth& 
DESCRIPTION 

ORDERS assumes that the n records to be sorted are of length ireclth and have been stored in an array 
data that has been dimensioned, as in the following Fortran code: 

DIMENSION DATA(ireclth,n) 

ORDERS does not move records within data, but returns a vector index containing pointers to each of 
the records in ascending order. For example, DATA(I,INDEX(1)) is the first word of the record with the 
smallest key. 

The ORDERS arguments are as follows: 

mode Integer flag; describes the type of key and indicates an initial ordering of the records, as 
follows: 

0 The key is binary numbers of length %*ikeylth. These numbers are considered posi- 
tive integers in the range 0 to 2 i ** ir * clth) ~ 1 . (The ordering of ASCII characters is the 
same as their ordering as positive integers.) 

1 The key is 64-bit Cray integers. These are twos complement signed integers in the 
range -2 63 to +2 63 . (The key length* if specified, must be 8 bytes.) 

2 The key is 64-bit Cray floating-point numbers. (The key length, if specified, must 
be 8 bytes.) 

10 The key is the same as mode-Q, but the array INDEX has an initial ordering of the 
records (see subsection MULTIPASS SORTING later in this section). 

11 The key is the same as mode=l > but the array INDEX has an initial ordering of the 
records. 

12 The key is the same as mode-2, but the array INDEX has an initial ordering of the 
records. 
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Upon completion of a call, ORDERS returns an error flag in mode. A value equal to the 
input mode value indicates no errors. A value less than 0 indicates an error, as follows: 

-1 Too few arguments; must be greater than 4. 

-2 Too many arguments; must be less than 9. 

-3 Number of words per record less than 1 or greater than 2**24 

-4 Length of key greater than the record 

-5 Radix not equal to 1 or 2 

-6 Key less than 1 byte long 

-7 Number of records less than 1 or greater than 2**24 

•8 Invalid mode input values; must be 0, 1, 2* 10, 11, or 12. 

-9 Key length must be 8 bytes for real or integer sort 

iwork User-supplied working storage array of length K, where K=257 if iradsi2=l t or K=65537 if 
iradsiz=2 

data Array dimensioned ireclth by N, containing N records of length ireclth each. The key in 
each record starts at the left of the first word of the record and continues ikeylth bytes into 
successive words as necessary. (By offsetting this address, any word within the record may 
be used as a key. See subsection EXAMPLES later in this section.) 

index Integer array of length n containing pointers to the records. In mode=10 f 11, or 12, index 
contains an initial ordering of the records (see subsection MULTIPASS SORTING later in this 
section). On output, index contains the ordering of the records; that is, DATA(1JNDEX(I)) 
is the first word of the record with the smallest key, and DATA(1JNDEX(N)) is the first 
word of the record with the largest key. 

n Number of records to be sorted. Must be >1. 

ireclth Length of each record as a number of 64-bit words. Default is 1. ireclth is used as a skip 
for vector loads and stores; therefore, ireclth should be chosen to avoid bank conflicts. 

ikeylth Length of each key as a number of 8-bit bytes. Default is 8 bytes (1 word). 

iradsiz Radix of the sort iradsiz is the number of bytes processed per pass over the records. 
Default is 1. See subsection of LARGE RADIX SORTING for iradsiz^!. 
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METHOD 

ORDERS uses the radix sort, more commonly known as a bucket or pocket sort. For this type of sort, 
the length of the key in bytes determines the number of passes made through all of the records. The 
method has a linear work factor and is stable, in that the original order of records with equal keys is 
preserved. 

ORDERS has the option of processing 1 or 2 bytes of the key per pass through the records. This pro- 
cess halves the number of passes through the record, but at the expense of increased working storage 
and overhead per pass, ORDERS can sort on several keys within a record by using its multipass capa- 
bility. The first 8 bytes of the keys use a radix sort If the key length is greater than 8 bytes and any 
records have the first 8 bytes equal, these records are sorted using a simple bubble sort. Using the bub- 
ble sort with many records is time-consuming; therefore, the multipass option should be used, 

ORDERS has been optimized in CAL to make efficient use of the vector registers and functional units at 
each step of a pass through the data. Keys are read into vector registers with a skip through memory of 
ireclth; therefore, ireclth should be chosen to avoid bank conflicts. 



LARGE RADIX SORTING 

The number of times the key of each record is read from memory is proportional to ikeylthfiradsiz. 
Using ORDERS with iradsiz-2 halves this r#tio because 2 bytes instead of 1 are processed each time 
the key is read. The disadvantage of halving the number of passes is that the user-supplied working 
storage array goes from 257 words to 65,537 words. This favors a 1-byte pass for sorting up to approx- 
imately 5000 records. For more than 5000 records, however, a 2-byte pass is faster. 



MULTIPASS SORTING 

Because the array INDEX can define an ordering of the records, several calls can be made to ORDERS 
where the order of the records is that of the previous call. rnode=l0, 11, or 12 specifies that the array 
INDEX contains an ordering from a previous call to ORDERS. This specification allows sorting of text 
keys that extend over more than 1 word or keys involving double-precision numbers. (See the subsec- 
tion EXAMPLES later in this section.) 

Although the length of the key is limited only by the length of the record, up to 8 bytes are sorted with 
the radix sort. The remaining key is sorted using a bubble sort, but only in those records whose keys 
are equal for the first 8 bytes. Therefore, a uniformly-distributed key over the first 8 bytes of length 
greater than 8 bytes might be sorted faster using a single call with a large ikeylth rather than a mul- 
tipass call. When using the multipass capability, sort the least significant word first. 

IMPLEMENTATION 

ORDERS is available to users of both the COS and UNICOS operating systems. 
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EXAMPLES 



Example 1: 

This example performs a sort on an array of random numbers, 20 records long, with a key length of 8 
bytes (1 word). 

PROGRAM ORDWAY 
DIMENSION DATA(1,20) 
DIMENSION INDEX(20) 
DIMENSION IWORK(257) 

C 

C Place random numbers into the array DATA 

C 

DO 1 1=1,20 

1 DATA(1,I)=2*RANF() 

C 

N=20 
MODE=0 

C 

CALL ORDERS (MODE,IWORK,DATA,INDEX,N,l ,8,1) 

C 

C Print out the sorted records in increasing order 

C 

DO 2 K= 1,20 

2 PRINT *, DATA(1 ,INDEX(K)) 
STOP 

END 



Example 2: 

This program uses two calls to ORDERS to completely sort an array of double-precision numbers. The sign 
bit of the first word is used to change the second word into a text key that preserves the ordering. A sort is 
done on these 6 bytes of the second word. (The changes made to the second word are reversed after the 
call.) Last, a sort is done on the first word as a real key using the initial ordering from the previous call. 

PROGRAM SORT2 

DOUBLE PRECISION DATA(IOO) 

INTEGER IATA(200) 

EQUIVALENCE(IATA, DATA) 

INTEGER INDEX(IOO), IWORK(257) 

N=12 

DO 5 1=1, N 

DATA(I)=(-1.D0)**10.D0**(-20)*DBLE(RANF0) 
5 CONTINUE 
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C 

C First the second word key is changed 

C 

DO10I=2,2*N,2 

IF(DATA(I/2).LE.0.DO) THEN 
IATAa)=COMPL(IATA(I)) 
ELSE 

IATA(I>IATA(I) 
ENDIF 
10 CONTINUE 

C 

C Sort on second word 

C 

MODE=0 

CALLORDERS(MODE,IWORK,IATA(2),INDEX,N,2, 6, 1) 

C 

C Restore second word to original form 

C 

DO20I=2,2*N,2 

IF(DATA(1/2).LE.0.D0) THEN 
IATAa)=COMPL(IATA(I)) 
ELSE 

IATA(I)=IATA(I) 
ENDIF 
20 CONTINUE 

C 

C Sort on the first word using the initial ordering 

C 

MODE=12 

CALL ORDERS(MODE,SORT,DATA,INDEXJN,2,8 ,1) 

DO 50 1=1 ,N 

WRITE(6, 900)1, INDEX(I), DATA(INDEX(I)) 
50 CONTINUE 
900 FORMAT(1X,2I5,2X,D40.30) 

END 
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8. CONVERSION SUBPROGRAMS 



These Fortran-callable subroutines perform conversion of data residing in Cray memory. Conversion 
subprograms are listed under the following types of routines: 

• Foreign data conversion 

• Numeric conversion 

• ASCII conversion 

• Other conversion 

For more information regarding foreign data conversion, see the Foreign Data Conversion on CRAY-1 
and CRAY X-MP Computer Systems technical note, publication SN-0236. 

FOREIGN DATA CONVERSION ROUTINES 

The foreign data conversion routines allow data translation between Cray internal representations and 
other vendors* data types. These include IBM, CDC, and VAX data conversion routines. 

The following tables convert values from Cray data types to IBM, VAX/VMS, and CDC data types. Rou- 
tines that are inverses of each other (that is, convert from Cray data types to IBM and IBM to Cray) are 
generally listed under a single entry. Routine descriptions follow later in this section, listed alphabeti- 
cally by entry name. 

The following table lists routines that convert foreign types to Cray types. 



Convert Foreign Types to Cray Types 


Convert to 

Convert from 


Foreign types 


IBM 


CDC 


VAX/VMS 


Foreign single-precision to 
Cray single-precision 


USSCTC 


FP6064 


VXSCTC 


Foreign double-precision to 
Cray single-precision 


USDCTC 




VXDCTC 
VXGCTC 


Foreign integer to Cray integer 


USICTC 


INT6064 


VXICTC 


Foreign logical to Cray logical 


USLCTC 




VXLCTC 


Foreign character to ASCII 


USCCTC 


DSASC 




Foreign complex to Cray 
complex 






VXZCTC 


Foreign packed decimal field to 
Cray integer 


USPCTC 
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The following table lists routines that convert Cray types to foreign types. 



Convert Cray Types to Foreign Types 


Convert To 

Convert From 


Foreign Types 


IBM 


CDC 


VAX/VMS 


Cray single-precision to 
foreign single-precision 


USSCTI 


FP6460 


VXSCTI 


Cray single-precision to 
foreign double-precision 


USDCTI 




VXDCTI 
VXGCTI 


Cray integer to foreign integer 


USICTI 


INT6460 


VXICTI 


Cray logical to foreign logical 


USLCTI 




VXLCTI 


ASCII character to foreign 
character 


USCCTI 


ASCDC 




Cray complex to foreign complex 






VXZCTI 


Cray integer to foreign packed- 
decimal field 


USICTP 







NUMERIC CONVERSION ROUTINES 

Numeric conversion routines convert a character to a numeric format or a number to a character fomiat. 
The following table contains the purpose, names > and entry of each numeric conversion routine. 



Numeric Conversion Routines 


Purpose 


Name 


Entry 


Convert decimal ASCII numerals to an 
integer value 


CHCONV 


CHCONV 


Convert an integer to a decimal ASCII string 


BICONV 


BICONV 


Convert an integer to a decimal ASCII string 
(zero-filled, right-justified) 


BICONZ 



ASCH CONVERSION FUNCTIONS 

The ASCH conversion functions convert binary integers to or from 1-word ASCII strings (not Fortran 
character variables). Fortran-callable entry points (in the form xxx) use the call-by-address sequence; 
CAL-callable entry points (in the form xxx%) use the call-by-value sequence. 

NOTE - The ASCH conversion functions are not intrinsic to Fortran. Their default type is real, even 
though their results are generally used as integers. 

IMPLEMENTATION - The ASCII conversion functions are available to users of both the COS and 
UNICOS operating systems. 

Hie ASCH conversion routines use one type integer argument. The DTB/DTB % and OTB/OTB% rou- 
tines can also use a second optional argument as an error code. The resulting enor codes (0 if no error; 
-1 if there are errors) are returned in the second argument for Fortran calls and in register SO for CAL 
calls. If no error code argument is included in Fortran calls, the routine aborts upon encountering an 
error. 
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The following calls show how the ASCII conversion routines are used. These Fortran calls convert a 
binary number to decimal ASCII, then convert back from ASCII to binary: 

result=BTD(integer) 

result Decimal ASCII result (right-justified, blank-filled) 
integer Integer argument 

result=DTB(arg,errcode) 
result Integer value 

arg Decimal ASCII (left-justified, zero-filled) 

err code 0 if conversion successful; -1 if error. 



ASCII Conversion Routines 


Purpose 


Name 


Argument 
Range 


Result 


Binary to decimal ASCII 

(right-justified, 

blank-filled) 


BTD 
BTD% 


0<x<99999999 


One- word ASCII string 

(right-justified, 

blank-filled) 


Binary to decimal ASCII 

(left-justified, 

zero-filled) 


BTDL 
BTDL% 


0<x<99999999 


One-word ASCII string 

(left-justified, 

zero-filled) 


Binary to decimal ASCII 

(right-justified, 

zero-filled) 


BTDR 
BTDR% 


0<x ^99999999 


One-word ASCII string 

(right-justified, 

zero-filled) 


Binary to octal ASCII 

(right-justified, 

blank-filled) 


BTO 

BTO% 


0<x<77777777 8 


One-word ASCII string 

(right-justified, 

blank-filled) 


Binary to octal ASCII 

(left-justified, 

zero-filled) 


BTOL 
BTOL% 


(Kx<77777777 8 


One-word ASCII string 

(left-justified, 

(zero-filled) 


Binary to octal ASCII 

(right-justified, 

zero-filled) 


BTOR 
BTOR% 


<K*<77777777 8 


One-word ASCII string 

(right-justified, 

zero-filled) 


Decimal ASCII to binary 


DTB 
DTB% 


Decimal ASCII 

(left-justified, 

zero-filled) 


One word containing 
decimal equivalent of 
ASCII string 


Octal ASCII to binary 


OTB 
OTB % 


Octal ASCII 

(left-justified, 

zero-filled) 


One word containing 
octal equivalent of 
ASCII string 



SR-0113 



INTRO(3X) 



INTRO (3X) 



OTHER CONVERSION ROUTINES 

These routines place the octal ASCII representation of a Cray word into a character area, convert trailing 
blanks to nulls or trailing nulls to blanks, and translate a string from one code to another, using a trans- 
lation table. 

The following table contains the purpose, name, and entry of these conversion routines. 



Other Conversion Routines 


Purpose 


Name 


Entry 


Place an octal ASCII representation of 
a Cray word into a character area 


B20CT 


B20CT 


Convert trailing blanks to nulls 


RUN 


RBN 


Convert trailing nulls to blanks 


RNB 


Translate a string from one code to 
another, using a translation table 


TR 


TR 
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NAME 



B20CT - Places an octal ASCII representation of a Cray word into a character aiea 



SYNOPSIS 



CALL B20CT(5jJt l v,ii) 



DESCRIPTION 



s 



First word of an array where the ASCII representation is to be placed 



J 



Byte offset within array s where the first character of the octal representation is to be 
placed. A value of 1 indicates that the destination begins with the first (leftmost) byte of 
the first word of $. j must be greater than 0. 



k 



Number of characters used in the ASCII representation; k must be greater than 0. k indi- 
cates the size of the total area to be filled, and the area is blank-filled if necessary. 



v 



Value to be converted. The low-order n bits of word v are used to form the ASCII 
representation, v must be less than or equal to 2 63 -L 



n 



Number of low-order bits of v to convert to ASCII character representation (l£n<64). If 
insufficient character space is available (3k<n) f the character region is automatically filled 
with asterisks (*). 



B20CT places the ASCII representation of the low-order n bits of a full Cray word into a specified char- 
acter area 

The k characters in array s, pointed to by j 9 are first set to blanks. The low-order n bits of v are then 
converted to octal ASCII, using leading zeros if necessary. The converted value (n/i characters, 
rounded up) is right-justified into the blanked-out destination character region. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

BICONV, BICONZ - Converts a specified integer to a decimal ASCII string representing the integer 

SYNOPSIS 

CALL BICOW(jnt4est,isb,len) 
CALL BICOfiZiint,destjsb,ten) 

DESCRIPTION 



int Integer variable, expression, or constant to be converted (input) 

dest Variable or array of any type or length to contain the ASCII result (output) 

isb Starting byte count to generate the output string. Specify an integer variable, expression, or 

constant Bytes are numbered from 1, beginning at the leftmost byte position of dest. 
(input) 

len Number of bytes desired in the ASCII result (input) 



BICONV converts a specified integer to an ASCH string. The string generated by BICONV is blank- 
filled, right-justified, and has a maximum width of 256 bytes. If the specified field width is not long 
enough to hold the converted integer number, left digits are truncated and no indication of overflow is 
given* If the number to be convened is negative, a minus sign is positioned in the output field to the 
left of the first significant digit 

BICONZ is the same as BICONV except that the output string generated is ASCII-zero-filled> right- 
justified, (A minus sign, if any, appears in the leftmost character position of the field.) 

IMPLEMENTATION 

These routines are available only to users of the COS operating system. 

NOTES 

Unused bytes in dest are left undisturbed. 
EXAMPLES 

The output from these examples uses the letter x for unprintable characters. If the variable int is zero, 
the routine returns blanks or zeros for the specified bytes of variable jdesu 

PROGRAM TEST 

INTEGER INTJHEXF JDEST 

DATA IHEXF/X^EFHWFFFFFFFFFFV 

* TEST BICONV 

* Example 1: Convert contents of INT from byte 8 for 1 byte 

INT=-12034056 
JDEST=IHEXF 

CALL BICONV(INTJDEST,8,l) 
Output: 

INT= -12034056 JDEST=xxxxxxx6 
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* Example 2: Convert contents of INT from byte 1 for 8 bytes 

INT=89001200 
JDEST=IHEXF 

CALL BICONV(INT,JDEST,l,8) 
Output: 

INT= 89001200 JDEST= 89001200 

* Example 3: Convert contents of INT from byte 3 for 6 bytes 

JDEST=MEXF 

CALL BICONV(INT,JDEST,3,6) 
Output: 

INT= 89001200 JDEST= xx001200 

* Example 4: Convert contents of INT from byte 5 for 3 bytes 

INT=12034056 
JDEST=IHEXF 

CALL BICONV(INT,JDEST,5,3) 
Output: 

INT= 12034056 JDEST=xxxx056x 

* Example 5: Convert contents of zero INT from byte 3 for 3 bytes 

INT=0 

JDEST=IHEXF 

CALL BICONV(INTJDEST,3,3) 
Output: 

INT= 0 JDEST= xx xxx 

* Example 6: Convert smaller number than needed 

ENT=99 
JDEST==IHEXF 

CALL B ICONV(INT JDES T, 1 ,6) 
Output: 

INT= 99 JDEST= 99xx 
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* Example 7: Convert smaller number than needed 

JDEST=IHEXF 
INT— 99 

CALL BICONV(INT JDEST.2,6) 
Output: 

INT= -99 JDEST- x -99x 



*TESTBICONZ 

* Example 1 A: Convert contents of INT from byte 8 for 1 byte 

INT= 12034056 
JDEST=IHEXF 

CALL BICONZ(INT r rDEST,8,l) 
Output: 

INT= 12034056 JDEST= xxxxxxx6 

* Example 2A: Convert contents of INT from byte 1 for 8 bytes 

INT=89001200 
JDEST=IHEXF 

CALL BICONZ(INTJDEST,l,8) 
Output: 

INT= 89001200 JDEST= 89001200 

* Example 3 A: Convert contents of INT from byte 3 for 6 bytes 

JDEST=IHEXF 

CALL BICONZ(INTJDEST,3,6) 
Output: 

INT= 89001200 JDEST=xx001200 

* Example 4 A: Convert contents of INT from byte 5 for 3 bytes 

INT=-12034056 
JDEST=IHEXF 

CALL BICONZ(TNTJDEST,5,3) 
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Output: 

INT= -12034056 JDEST=xxxx056x 

* Example 5 A: Convert contents of zero INT from byte 3 for 3 bytes 

INT=0 

JDEST=IHEXF 

CALL BICONZ(INTJDEST,3,3) 
Output: 

INT= 0 JDEST= xxOOOxxx 

* Example 6A: Convert smaller number than needed 

INT=99 

JDEST=IHEXF 

CALL BICONZ(INT r rDEST,l,6) 
Output: 

INT= 99 JDEST=000099xx 

* Example 7A: Convert smaller number than needed 

JDEST=IHEXF 
INT=-99 

CALL BICONZ(INTJDEST t 2,6) 
Output: 

INT= -99 JDEST=x-00099x 
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NAME 

CHCONV - Converts decimal ASCII numerals to an integer value 

SYNOPSIS 

CALL CHCONV(src4sb,num t ir) 

DESCRIPTION 

src Variable or array of type Hollerith containing ASCII data or blanks 

isb Starting character in the src string. Specify an integer variable, expression, or constant. 

Characters are numbered from 1, beginning at the leftmost character position of src, 

num Number of ASCII characters to convert. Specify an integer variable, expression, or constant. 

ir Integer result 

Blanks in the input field are treated as zeros. A minus sign encountered anywhere in the input field 
produces a negative result Input characters other than blank, digits 0 through 9, a minus sign, or more 
than one minus sign produce a fatal error, 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

DSASC, ASCDC - Converts CDC display code character to ASCII character and vice versa 

SYNOPSIS 

CALL D$ASC(src,sc,dest,num) 
CALL A$CDC(src,sc t de$t t num) 

DESCRIPTION 

src For DSASC, a variable or array of any type or length containing CDC display code charac- 

ters (64-character set), left-justified in a 64-bit Cray word. Contains a maximum of 10 
display code characters per word. For ASCDC, a variable or array of any type or length 
containing ASCII data. 

sc Display code or ASCII character position to begin the conversion. Leftmost position is 1. 

dest For DSASC, a variable or array of any type or length to contain the converted ASCII data. 

Results are packed 8 characters per word. For ASCDC, a variable or array of any type or 
length to contain the converted CDC display code characters (64-character set). Results are 
packed into continuous strings without regard to word boundaries. 

num Number of CDC display code or ASCII characters to convert. Specify an integer variable, 
expression* or constant. 

DSASC converts CDC display code characters to ASCII character. 

ASCDC converts ASCII characters to CDC display code characters. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

FP6064, FP6460 - Converts CDC 60-bit single-precision numbers to Cray 64-bit single-precision 
numbers and vice versa 

SYNOPSIS 

CALL YVGMMfpntdesttnum) 
CALL FY646fb(fpn4est,num) 

DESCRIPTION 

fpn For FP6064> a variable or array of any type or length containing CDC 60-bit, single- 

precision numbers, left-justified in a Cray 64-bit word. For FP6460, a variable or array of 
any length and of type real containing Cray single-precision numbers. 

dest Variable or array of type real to contain the converted Cray 64-bit, single-precision or CDC 

60-bit single-precision numbers. (In FP6460, each floating-point number is left-justified in a 
64-bit word.) 

nam Number of CDC or Cray single-precision numbers to convert. Specify an integer variable, 

expression, or constant. 

FP6064 converts CDC 60-bit single-precision numbers to Cray 64-bit single-precision numbers. 
FP6460 converts Cray 64-bit single-precision numbers to CDC 60-bit single-precision numbers. 

IMPLEMENTATION 

These routines are available to users of the both the COS and UNICOS operating systems. 
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NAME 

INT6064 - Converts CDC 60-bit integers to Cray 64-bit integers 

SYNOPSIS 

CALL IST6064(src f idest t num) 

DESCRIPTION 

src Variable or array of any type or length containing CDC 60-bit integers, left-justified in a 

Cray 64-bit word 

iciest Variable or array of type integer to contain the converted values. Each such integer is left- 
justified and zero-filled. 

num Number of CDC integers to convert Specify an integer variable, expression, or constant. 
INTW64 converts CDC 60-bit integer numbers to Cray 64-bit integer numbers. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

INT6460 is the inverse of this routine 
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NAME 

INT6460 - Converts Cray 64-bit integers to CDC 60-bit integers 

SYNOPSIS 

CALL 1NT6460(in,idest t num) 

DESCRIPTION 

in Variable or array of any length and of type integer containing Cray integer numbers 

idest Variable or array of type integer to contain the converted values or CDC integer numbers. 
Each such integer is left-justified and zero-filled. 

num Number of Cray integers to convert Specify an integer variable, expression, or constant 

INT6460 converts Cray 64-bit integer numbers to CDC 60-bit integer numbers. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

INT6064 is the inverse of this routine 
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NAME 

RBN, RNB - Converts trailing blanks to nulls and vice versa 

SYNOPSIS 

noblanks=RB?i(blanks) 
blanks=RNB (noblanks) 

DESCRIPTION 

blanks For RBN, the argument to be converted. 

For RNB, the argument after conversion. 

noblanks For RBN, the argument after conversion. 

For RNB, the argument to be converted. 

RBN converts trailing blanks to nulls. 
RNB converts trailing nulls to blanks. 

NOTE 

Fortran programs using RBN or RNB must declare the function to be type integer. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

TR - Translates a string from one code lo another using a translation table 

SYNOPSIS 

CALL TR(sj t k,table) 

DESCRIPTION 

s First word of an array containing the characters to be translated 

j Byte offset within array s where the first character to be translated occurs 

k Number of characters to be translated 

table Translation table 

TR translates a string in place from one character code to another using a user-supplied translation 
table. The routine assumes 8-bit characters. 

The translation table must be considered a string of 256 bytes (32 words). As each character to be 
translated is fetched, it is used as an index into the translation table. The new value of the character is 
the content of the translation-table byte addressed by the old value, (The first byte of the translation 
table is considered to be byte 0.) 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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TRRl(3COS) 



NAME 

TRR1 - Translates characters stored one character per word 

SYNOPSIS 

CALL TRRl(s,k t table) 

DESCRIPTION 

5* Array containing the characters to be translated 

k Number of characters to be translated 

table Translation table 

TRR1 translates k characters, stored one character per word, right-justified, zero-filled, in array s using 
the translation table table. 

table is a 256-word array (dimensioned (0:255)) containing the translation for each character in the 
entry for the character viewed as an integer. 

TRR1 leaves 5(1) unchanged if s(X) is not in die range 0,...,255. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

USCCTC, USCCTI - Converts IBM EBCDIC data to ASCII data and vice versa 
SYNOPSIS 

CALL VSCCTC(src t isb t dest,num t npwivall) 
CALL VSCCTl(src,dest l isb,nwn,npw[,var}) 

DESCRIPTION 

src Variable or array of any type or length containing IBM EBCDIC data or ASCII data, left- 

justified, in Cray words, to convert 

isb For USCCTC, a byte number to begin the conversion. Specify an integer variable, expres- 

sion, or constant. Bytes are numbered from I, beginning at the leftmost byte position of 
src. For USCCTI, a byte number at which to begin generating EBCDIC characters in dest 

dest Variable or array of any type or length to contain the IBM EBCDIC or ASCII data 

num Number of IBM EBCDIC or ASCII characters to convert Specify an integer variable, 
expression, or constant, 

npw Number of characters per word generated in dest (or selected from src in USCCTI). The 
npw characters are left-justified and blank>filled in each word of dest Specify an integer 
variable, expression, or constant Value must be from 1 to 8. 

val A value of nonzero specifies lowercase characters (a through z) that are to be translated to 

uppercase. A value of 0 results in no case translation. This is an optional parameter 
specified as an integer variable, expression, or constant The default is no case translation. 

USCCTC converts IBM EBCDIC data to ASCII data. The same array can be specified for output as for 
input only if isb = 1 and npw = 8. 

USCCTI converts ASCII data to IBM EBCDIC data. All unprintable characters are convened to blanks. 
The same array can be specified for output as for input only if isb * 1 and npw = 8. 

NOTE 

You may also find routine TR (described in this section) useful. It provides somewhat more control over 
the specific translation used, although it does require the translation to be done in place. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

USDCTC - Converts IBM 64-bit floating-point numbers to Cray 64-bit single-precision numbers 

SYNOPSIS 

CALL \}SBCT:C(dpn t isb t d€st t numlinc]) 

DESCRIPTION 

dpn Variable or array of any type or length containing IBM 64-bit floating-point numbers to con- 

vert 

isb Byte number to begin the conversion. Specify an integer variable, expression, or constant. 

Bytes are numbered from 1 , beginning at the leftmost byte position of fpn or dpn. 

dest Variable or array of type real to contain the converted values 

num Number of IBM 64-bit floating-point numbers to convert. Specify an integer variable, 

expression, or constant. 

inc Memory increment for storing the conversion results in dest. This is an optional parameter 

specified as an integer variable, expression, or constant The default value is L 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

USDCTI is the inverse of this routine. 
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NAME 

USDCTI - Converts Cray 64-bit single-precision, floating-point numbers to IBM 64-bit double precision 
numbers 

SYNOPSIS 

CALL VSDCTItfpn4est,isbwm,ier[ t inc]) 

DESCRIPTION 

fpn Variable or array of any length and type real, containing Cray 64-bit single-precision, 

floating-point numbers to convert 

dest Variable or array of type real to contain the converted values 

isb Byte number at which to begin storing the converted results. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position 
of dest. 

nam Number of Cray floating-point numbers to convert. Specify an integer variable, expression, 
or constant. 

ier Overflow indicator of type integer. Value is 0 if all Cray values convert to IBM values 

without overflow. Value is nonzero if one or more Cray values overflowed in the conver- 
sion. 

inc Memory increment for fetching the number to be converted. This is an optional parameter 

specified as an integer variable, expression, or constant The default value is 1. 

USDCTI converts Cray 64-bit single-precision, floating-point numbers to IBM 64-bit double-precision, 
floating-point numbers. Precision is extended by introducing 8 more bits into the rightmost byte of the 
fraction from the Cray number being converted. Numbers that produce an underflow when converted to 
IBM format are converted to 64 binary Os. Numbers that produce an overflow when converted to IBM 
format are converted to the largest IBM floating-point representation with the sign bit set if negative. 
An error parameter returns nonzero to indicate that one or more numbers converted produced an 
overflow. No such indication is given for underflow. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

USDCTC is the inverse of this routine. 
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NAME 

USICTC, USICTI - Converts IBM INTEGER*2 and INTEGERM numbers to Cray 64-bit integer numbers, 
and vice versa 

SYNOPSIS 

CALL \}^lCTC(in f isb4est t num t len[ t inc\) 
CALL VSICTL(inMestM,numJen,ierUnc]) 

DESCRIPTION 

in Variable or array of any type or length containing IBM INTEGER*^ or INTEGER*4 numbers 

or Cray 64-bit integers to convert 

isb Byte number at which to begin the conversion or at which to begin storing the converted 

results. Specify an integer variable, expression, or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of in (dest in USICTI). 

dest Variable or array of type integer to contain the converted values 

num Number of IBM numbers or Cray integers to convert Specify an integer variable, expres- 
sion, or constant. 

len Size of the IBM numbers to convert or of IBM result numbers. These values must be 2 or 

4. A value of 2 indicates that input or output integers are INTEGER*2 (16-bit). A value of 
4 indicates that input or output integers are INTEGERM (32-bit). Specify an integer vari- 
able, expression, or constant. 

inc Memory increment for storing the conversion results in dest or for fetching the number to 

be converted. This is an optional parameter specified as an integer variable, expression, or 
constant The default value is 1 . 

ier Overflow indicator of type integer. The value is zero if all Cray values converted to IBM 

values without overflow. The value is not zero if one or more Cray values overflowed in 
the conversion. 

USICTC converts IBM INTEGER*2 and INTEGER*4 numbers to Cray 64-bit integer numbers. 

USICTI converts Cray 64-bit integer numbers to IBM INTEGER*2 or INTEGER*4 numbers. 

Numbers that produce an overflow when converted to IBM format are converted to the largest IBM 
integer representation, with the sign bit set if negative. An error parameter returns nonzero to indicate 
that one or more of the numbers converted produced an overflow. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

USICTP - Converts a Cray 64-bit integer to IBM packed-decimal field 

SYNOPSIS 

CALL \JSICTP(ian t dest,isb,num) 

DESCRIPTION 

ion Cray integer to be converted to an IBM packed-decimal field. Specify an integer variable, 

expression, or constant. 

dest Variable or array of any type or length to contain the packed field generated 

isb Byte number within dest specifying the beginning location for storage. Specify an integer 

variable, expression, or constant. Bytes are numbered from 1, beginning at the leftmost 
byte position of dest. 

num Number of bytes to be stored. Specify an integer variable, expression, or constant. 

If the input value contains more digits than can be stored in num bytes, the leftmost digits are not con- 
verted. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

USPCTC is the inverse of this routine. 
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NAME 

USLCTC, USLCTI - Converts IBM LOGICAL* 1 and LOGICAL*4 values into Cray 64-bit logical values, 
and vice versa 

SYNOPSIS 

CALL USLCTC(src t isb4est t num,lenlinc]) 
CALL VSL,CTI(src, dest, isb. num Jenlinc]) 

DESCRIPTION 

src Variable or array of any type (type logical in USLCTI) and any length containing IBM LOG- 

ICAL*!, LOGICAL*4 9 or Cray logical values to convert. 

isb Byte number to begin the conversion or, in USLCTI, specifying the beginning location for 

storage. Specify an integer variable, expression, or constant. Bytes are numbered from 1, 
beginning at the leftmost byte position of src. 

dest Variable or array of any type or length to contain the converted values 

num Number of IBM or Cray logical values to be converted. Specify an integer variable, expres- 

sion, or constant. 

len Size of the IBM logical values to convert or of the logical result value. These values must 

be I or 4. A value of 1 indicates that input or output logical values are LOGlCAL*l (8-bit). 
A value of 4 indicates that input or output logical values are LOGICAL*4 (32-bit). Specify 
an integer variable, expression, or constant. 

inc Memory increment for storing the conversion results in dest or for fetching the number to 

be converted. This is an optional parameter specified as an integer variable, expression, or 
constant. The default value is 1. 

USLCTC converts IBM LOGICAL* 1 and LOGICAL*4 values to Cray 64-bit logical values. 
USLCTI converts Cray logical values to IBM LOGICAL*! or LOGICAL*^ values. 

All arguments must be entered in the same order in which they appear in the synopsis. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

USPCTC - Converts a specified number of bytes of an IBM packed-decimal field to a 64-bit integer 
field 

SYNOPSIS 

CALL \JSPCTC(src4sb t num t ian) 

DESCRIPTION 



src Variable or array of any type or length containing a valid IBM packed-decimal field 

isb Byte number to begin the conversion. Specify an integer variable, expression, or constant. 

Bytes are numbered from 1, beginning at the leftmost byte position of src. 

num Number of bytes to convert Specify an integer variable, expression, or constant 

ian Returned integer result 



The input field must be a valid packed-decimal number less than 16 bytes long, of which only the right- 
most 15 digits are converted. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

USICTP is the inverse of this routine. 
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NAME 

USSCTC - Converts IBM 32-bit floating-point numbers to Cray 64-bit single-precision numbers 

SYNOPSIS 

CALL \J$$CTC(fpn,isb4est>num[>inc\) 

DESCRIPTION 

fpn Variable or array of any type or length containing IBM 32-bit floating-point numbers to con- 

vert 

isb Byte number to begin the conversion. Specify an integer variable, expression, or constant 

Bytes are numbered from 1, beginning at the leftmost byte position of fpn or dpn. 

dest Variable or array of type real to contain the converted values 

num Number of IBM 32-bit floating-point numbers to convert. Specify an integer variable, 
expression, or constant. 

inc Memory increment for storing the conversion results in dest. This is an optional parameter 

specified as an integer variable, expression, or constant The default value is 1. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems* 

SEE ALSO 

USSCTI is the inverse of this routine. 
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NAME 

USSCTI - Converts Cray 64-bit single-precision, floating-point numbers to IBM 32-bit single-precision 
numbers 

SYNOPSIS 

CALL USSCTIifpndestM,num t ier[ t inc]) 

DESCRIPTION 

fpn Variable or array of any length and type real, containing Cray 64-bit single-precision, 

floating-point numbers to convert 

dest Variable or array of type real to contain the converted values 

isb Byte number at which to begin storing the converted results. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position 
of dest. 

num Number of Cray floating-point numbers to convert. Specify an integer variable, expression, 

or constant. 

ier Overflow indicator of type integer. Value is 0 if all Cray values convert to IBM values 

without overflow. Value is nonzero if one or more Cray values overflowed in the conver- 
sion. 

inc Memory increment for fetching the number to be converted. This is an optional parameter 

specified as an integer variable, expression, or constant The default value is 1. 

USSCTI converts Cray 64-bit single-precision, floating-point numbers to IBM 32-bit single-precision, 
floating-point numbers. Numbers that produce an underflow when converted to IBM format are con- 
verted to 32 binary Os. Numbers that produce an overflow when converted to IBM format are converted 
to the largest IBM floating-point representation, with the sign bit set if negative. 

An error parameter returns nonzero to indicate that one or more numbers converted produced an 
overflow. No such indication is given for underflow. 

If you present this routine with invalid Cray floating-point numbers, a floating-point interrupt will result, 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

USSCTC is the inverse of this routine. 



SR-0113 



8-26 



D 



VXDCTC(3U) 



VXDCTC(3U) 



NAME 

VXDCTC - Converts VAX 64-bit D format numbers to Cray single-precision numbers 

SYNOPSIS 

CALL VXDCTC(dpn,isb,dest,num,[inc]) 

DESCRIPTION 

dpn Variable or array of any type or length containing VAX D format numbers to convert 

isb Byte number within dpn at which to begin the conversion. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte of dpn. 

dest Variable or array of type real to contain the converted values 

num Number of VAX D format numbers to convert. Specify an integer variable, expression, or 
constant 

inc Memory increment for storing the conversion results in dest. This is an optional parameter 

specified as an integer variable, expression, or constant. The default value is 1. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

VXDCTI is the inverse of this routine. 
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NAME 

VXDCTI - Converts Cray 64-bit single-precision, floating-point numbers to VAX D format floating-point 
numbers 

SYNOPSIS 

CALL VXXXCTl{fpn4est t isb t num t ierXinc\) 
DESCRIPTION 

fpn Variable or array of any length and type real containing Cray 64-bit single-precision, 

floating-point numbers to convert 

dest Variable or array of type real to contain the converted values 

isb Byte number at which to begin storing the converted results. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position 
of dest. 

num Number of Cray floating-point numbers to convert. Specify an integer variable, expression, 
or constant 

ier Overflow indicator of type integer. Value is 0 if all Cray values convert to VAX values 

without overflow. Value is nonzero if one or more Cray values overflowed in the conver- 
sion. 

inc Memory increment for fetching the number to be converted. This is an optional parameter 

specified as an integer variable, expression, or constant 

Numbers that produce an underflow when converted to VAX format are converted to 32 binary Os. 
Numbers that are in overflow on the Cray computer system are converted to a "reserved" floating-point 
representation, with the sign bit set if negative. Numbers that are valid on the Cray computer system 
but overflow on the VAX are converted to the most positive possible number or most negative possible 
number, depending on the sign. 

An error parameter returns nonzero to indicate that one or more numbers converted produced an 
overflow. (Deferred implementation; at present, you must supply the parameter, which is always 
returned as 0.) No such indication is given for underflow. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems, 

SEE ALSO 

VXDCTC is the inverse of this routine. 
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NAME 

VXGCTC - Converts VAX 64-bit G format numbers to Cray single-precision numbers 

SYNOPSIS 

CALL yXGCTC{dpnMb4est^um t \inc\) 

DESCRIPTION 

dpn Variable or array of any type or length containing VAX G format numbers to convert 

isb Byte number within dpn at which to begin the conversion. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte of dpn. 

dest Variable or array of type real to contain the converted values 

nam Number of VAX G format numbers to convert Specify an integer variable, expression, or 

constant 

inc Memory increment for storing the conversion results in dest. This is an optional parameter 

specified as an integer variable, expression, or conxtant The default value is 1. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

VXGCH is the inverse of this routine* 
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NAME 

VXGCTI - Converts Cray 64-bit single-precision, floating-point numbers to VAX G format floating-point 
numbers 

SYNOPSIS 

CALL VXGCTl(fpn4est4sb,num,ier,[inc]) 
DESCRIPTION 

fpn Variable or array of any length and type real, containing Cray 64-bit single-precision, 

floating-point numbers to convert 

dest Variable or array of type real to contain the converted values 

isb Byte number at which to begin storing the converted results. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position 
of dest, 

num Number of Cray floating-point numbers to convert. Specify an integer variable, expression, 
or constant. 

ier Overflow indicator of type integer. Value is 0 if all Cray values convert to VAX values 

without overflow. Value is nonzero if one or more Cray values overflowed in the conver- 
sion. 

inc Memory increment for fetching the number to be converted. This is an optional parameter 

specified as an integer variable, expression, or constant The default value is 1. 

VXGCTI converts Cray 64-bit single-precision, floating-point numbers to VAX G format single- 
precision, floating-point numbers. 

Numbers that produce an underflow when converted to VAX format are converted to 32 binary zeros. 
Numbers that are in overflow on the Cray computer system are converted to a "reserved" floating-point 
representation, with the sign bit set if negative. Numbers that are valid on the Cray computer system 
but overflow on the VAX are converted to the most positive possible number or most negative possible 
number, depending on the sign. 

An error parameter returns nonzero to indicate that one or more numbers converted produced an 
overflow (Deferred implementation. At present, you must supply the parameter, which is always as 0.) 
No such indication is given for underflow. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

VXGCTC is the inverse of this routine. 
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NAME 

VXICTC - Converts VAX INTEGER*2 or INTEGER*4 to Cray 64-bit integers 

SYNOPSIS 

CALL \XlCTC(in t isb4est f numJen t [inc]) 

DESCRIPTION 



in Variable or array of any type or length containing VAX 16- or 32-bit integers 

isb Byte number at which to begin the conversion. Specify an integer variable, expression, or 

constant. Bytes are numbered from 1, beginning at the leftmost byte position of in, 

dest Variable or array of type integer to contain the converted values 

num Number of VAX integers to convert. Specify an integer variable, expression, or constant. 

len Size of the VAX numbers to convert This value must be 2 or 4. A value of 2 indicates 

that input integers are 16-bit A value of 4 indicates that input integers are 32-bit. Specify 
an integer variable, expression, or constant 

inc Memory increment for storing conversion results in dest. This is an optional parameter 

specified as an integer variable, expression, or constant. The default value is 1. 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

VXICTI is the inverse of this routine. 
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NAME 

VXICTI - Converts Cray 64-bit integers to either VAX JNTEGER*2 or INTEGERM numbers 
SYNOPSIS 

CALL VXlCTI(in4estisb,numJen t ier t [inc]) 
DESCRIPTION 

in Variable or array of any length and type integer, containing Cray integers to convert 

dest Variable or array of type integer to contain the converted values 

isb Byte number at which to begin storing the converted results. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position 
of dest 

num Number of Cray integers to convert. Specify an integer variable, expression, or constant. 

len Size of the VAX result numbers. This value must be 2 or 4. A value of 2 indicates that 

output integers are INTEGER*2 (16-bit). A value of 4 indicates that output integers are 
INTEGERS (32-bit). Specify an integer variable, expression, or constant. 

ier Overflow indicator of type integer. Value is 0 if all Cray values are converted to VAX 

values without overflow. Value is nonzero if one or more Cray values overflowed in the 
conversion. 

inc Memory increment for fetching the number to be converted. This is an optional parameter 

specified as an integer variable, expression, or constant The default value is 1. 

Numbers that produce an overflow when converted to VAX format are converted to the largest VAX 
integer representation, with the sign bit set if negative. 

An error parameter returns nonzero to indicate that one or more numbers converted produced an 
overflow. (Deferred implementation; at present, you must supply the parameter, which is always 
returned as 0.) No such indication is given for underflow. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems, 

SEE ALSO 

VXICTC is the inverse of this routine. 
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NAME 

VXLCTC - Converts VAX logical values to Cray 64-bit logical values 
SYNOPSIS 

CALL VXLCTC(srcjsbjd£st#umJentinc]) 
DESCRIPTION 

src Variable or array of any type or length containing VAX logical values to convert 

isb Byte number at which to begin the conversion. Specify an integer variable, expression, or 

constant Bytes are numbered from 1, beginning at the leftmost byte position of src. 

dest Variable or array of type logical to contain the converted values 

num Number of VAX logical values to be converted. Specify an integer variable, expression, or 
constant. 

len Size of the VAX logical values to convert At present, this parameter must be set to 4, indi- 

cating that 32-bit logical values are to be converted. Specify an integer variable, expres- 
sion, or constant. 

inc Memory increment for storing the conversion results in dest. This is an optional parameter 

specified as an integer variable, expression, or constant The default value is 1. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

VXSCTC - Converts VAX 32-bit floating-point numbers to Cray 64-bit single-precision numbers 

SYNOPSIS 

CALL VXSCTCtfpn t isb.dest,num f [inc]) 

DESCRIPTION 

fpn Variable or array of any type containing VAX 32-bit floating-point numbers to convert 

isb Byte number at which to begin the conversion. Specify an integer variable, expression, or 

constant. Bytes are numbered from 1, beginning at the leftmost byte position of fpn. 

dest Variable or array of type real to contain the converted values 

num Number of VAX floating-point numbers to convert* Specify an integer variable, expression, 

or constant. 

inc Memory increment for storing the conversion results in dest. This is an optional parameter 

specified as an integer variable, expression* or constant. The default value is 1. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

VXSCTI is the inverse of this routine. 
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NAME 

VXSCTI - Converts Cray 64-bit single-precision, floating-point to VAX F format single-precision, 
floating-point 

SYNOPSIS 

CALL \XSCTl(fpn4estM,num,ier,[inc]) 
DESCRIPTION 

fpn Variable or array of any length and type real, containing Cray 64-bit single-precision, 

floating-point numbers to convert 

dest Variable or array of type real to contain the converted values 

isb Byte number at which to begin storing the converted results. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position 
of dest. 

num Number of Cray floating-point numbers to convert. Specify an integer variable, expression, 

or constant 

ier Overflow indicator of type integer. Value is 0 if all Cray values convert to VAX values 

without overflow. Value is nonzero conversion. 

inc Memory increment for fetching the number to be converted. This is an optional parameter 

specified as an integer variable, expression, or constant The default value is 1. 

Numbers that produce an underflow when converted to VAX format are converted to 32 binary Os. 
Numbers that are in overflow on the Cray computer system are converted to a "reserved" floating-point 
representation, with the sign bit set if negative. Numbers that are valid on the Cray computer system 
but overflow on the VAX are converted to the most positive possible number or most negative possible 
number, depending on the sign. 

An error parameter returns nonzero to indicate that one or more numbers converted produced an 
overflow (Deferred implementation. At present you must supply the parameter, which is always 
returned as 0.) No such indication is given for underflow. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

VXSCTC is the inverse of this routine. 
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NAME 

VXZCTC - Converts VAX 64-bit complex numbers to Cray complex numbers 

SYNOPSIS 

CALL VXZCTC{dpn,isb t dest t num\inc\) 

DESCRIPTION 

dpn Variable or array of any type or length containing complex numbers to convert 

isb Byte number within dpn at which to begin the conversion. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte of dpn. 

dest Variable or array of type complex to contain the converted values 

num Number of complex numbers to convert Specify an integer variable, expression, or con- 
stant. 

inc Memory increment for storing the conversion results in dest. This is an optional parameter 

specified as an integer variable, expression, or constant Default value is 1. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

VXZCTI is the inverse of this routine. 
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NAME 

VXZCTI - Converts Cray complex numbers to VAX complex numbers 

SYNOPSIS 

CALL \XZCTI(fpn4est t isb,num t ier,[inc]) 

DESCRIPTION 

fpn Variable or array of any length and type complex, containing Cray complex numbers to 

convert 

dest Variable or array of any type to contain the converted values 

isb Byte number at which to begin storing the converted results. Specify an integer variable, 

expression, or constant. Bytes are numbered from 1, beginning at the leftmost byte position 
of dest. 

num Number of Cray floating-point numbers to convert Specify an integer variable, expression, 
or constant 

ier Overflow indicator of type integer. Value is 0 if all Cray values convert to VAX values 

without overflow. Value is nonzero if one or more Cray values overflowed in the conver- 
sion. 

inc Memory increment for fetching the number to be converted. This is an optional parameter 

specified as an integer variable, expression, or constant The default value is 1. 

Numbers that produce an underflow when converted to VAX format are converted to 32 binary zero. 
Numbers that are in overflow on the Cray computer system are converted to a "reserved" floating-point 
representation, with the sign bit set if negative. Numbers that are valid on the Cray computer system 
but overflow on the VAX are converted to the most positive possible number or most negative possible 
number, depending on the sign. 

An error parameter returns nonzero to indicate that one or more numbers converted produced an 
overflow (Deferred implementation. At present, you must supply the parameter, which is always 
returned as 0.) No such indication is given for underflow. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

VXZCTC is the inverse of this routine. 
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9. PACKING ROUTINES 



The packing routines provide alternative ways to pack and unpack data into or out of Cray words. The 
following table contains the purpose, name, and entry of each packing routine. 



Packing Routines 


Purpose 


Name 


Entry 


Pack 32-bit words into Cray 64-bit 
words 


P32 


P32 


Unpack 32-bit words from Cray 
64-bit words 


U32 


Pack 60-bit words into Cray 64-bit 


P6460 




words 




P6460 


Unpack 60-bit words from Cray 64-bit 
words 


U6064 


Compress stored data 


PACK 


PACK 


Expand stored data 


UNPACK 


UNPACK 
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NAME 

PACK - Compresses stored data 

SYNOPSIS 

CALL PACK(p,nbits,u,nw) 

DESCRIPTION 



p On exit, vector of packed data 

nbits Number of rightmost bits of data in each partial word; must be 1. 2, 4, 8, 16, or 32. 

u Vector of partial words to be compressed 

nw Number of partial words to be compressed 



PACK takes the 1, 2, 4, 8, 16, or 32 rightmost bits of several partial words and concatenates them into 
full 64-bit words. The following equation gives the number of full words: 

_ (nw -nbits) 
n ~ 64 

n Number of resulting full words 

nw Number of partial words 

nbits Number of rightmost bits of each partial word that contain useful data 
This equation restricts nw nbits to a multiple of 64. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

UNPACK 
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NAME 

P32, U32 - Packs/unpacks 32-bit words into or from Cray 64-bit words 

SYNOPSIS 

CALL F32(src,dest,num) 
CALL USlisrcMest.num) 

DESCRIPTION 

src For P32, a variable or array of any type or length containing 32-bit words, left-justified in a 

Cray 64-bit word. For U32, a variable or array of any type or length containing 32-bit 
words as a continuous stream of data. Unpacking always starts with the leftmost bit of src. 

dest For P32, a destination array of any type to contain the packed 32-bit woids as a continuous 

stream of data. For U32, a destination array of any type to contain the unpacked 32-bit 
words, left-justified and zero-filled in a Cray 64-bit word. 

num Number of 32-bit words to pack or unpack. Reads this many elements of src or generates 
this many elements of dest. Specify an integer variable, expression, or constant. 

P32 packs 32-bit words into Cray 64-bit words, U32 unpacks 32-bit words from Cray 64-bit words. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

P6460, U6064 - Packs/unpacks 60-bit words into or from Cray 64-bit words 

SYNOPSIS 

CALL P6460(src r dest,isb t num) 
CALL V6Q64farcjsb t destjutm) 

DESCRIPTION 

src Variable or array of any type or length containing 60-bit words, left-justified in a Cray 64- 

bit word (for U6064, words are contained as a continuous stream of data) 

dest For P6460, a destination array of any type to contain the packed 60-bit words as a continu- 
ous stream of data* For U6064, a destination array of any type to contain the unpacked 60- 
bit words, left-justified and zero-filled in a Cray 64-bit word. 

isb Bit location that is the leftmost storage location for the 60-bit words. Bit position is 

counted from the left to right, with the leftmost bit 0. Specify an integer variable, expres- 
sion, or constant 

num. Number of 60~bit words to pack or unpack. Reads this many elements of src or generates 
this many elements of dest. Specify an integer variable, expression, or constant* 

P6460 packs 60-bit words into Cray 64-bit words. U6064 unpacks 60-bit words from Cray 64-bit words. 
Parameter arguments must be addressed in the same order in which they appear in the synopsis above. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

UNPACK - Expands stored data 

SYNOPSIS 

CALL UNPACK(p,nfo"tt,u,flH>) 

DESCRIPTION 

p Vector of full 64-bit words to be expanded 

nbits Number of rightmost bits of data in each partial word; must be 1, 2, 4, 8, 16, or 32. 
u On exit, vector of unpacked data 

nw Number of resulting partial words 

UNPACK reverses the action of PACK and expands full words of data into a larger number of right- 
justified partial words. This routine assumes nw * nbits to be a multiple of 64. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

PACK 
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10, BYTE AND BIT MANIPULATION ROUTINES 



Byte and bit manipulation routines move bytes and bits between variables and arrays, compare bytes, 
perform searches with a byte count as a search argument, and perform conversion on bytes. 

The following table contains the purpose, name, and entry of each byte and bit manipulation routine. 



Byte and Bit Manipulation Routines 


Purpose 


Name 


Entry 


Replace a byte in a variable or an 
array with a specified value 


PUTBYT 


BYT 


Extract a byte from a variable 


IGTBYT 


Search a variable or an array for 
an occurrence of a character string 


F1NDCH 


FINDCH 


Compare bytes between variables or 
arrays 


KOMSTR 


KOMSTR 


Move bytes between variables or 
arrays 


STRMOV 


MOV 


Move bits between variables or 
arrays 


MOVBIT 


Move characters between memory areas 


MVC 


MVC 
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NAME 

PUTBYT, IGTBYT - Replaces a byte in a variable or an array 

SYNOPSIS 

value-YXYlhYTisiring^positionyalue) 
byte=IGTBYT(stringj>osition) 

DESCRIPTION 

string The address of a variable or an array. The variable or array may be of any type except 
character. 

position The number of the byte to be replaced or extracted This parameter must be an integer > 1. 

If position is <> 0, no change is made to the destination string; value returned is -1. For 
IGTBYT, if position is > 0, value is an integer between 0 and 255. 

value The new value to be stored into the byte. This parameter must be an integer with a value 
between 0 and 255. 

PUTBYT replaces a specified byte in a variable or an array with a specified value. IGTBYT extracts a 
specified byte from a variable or an array. 

If PUTBYT is called as an integer function (having been properly declared in the user program), the 
value of the function is the value of the byte stored. 

The high-order 8 bits of the first word of the variable or array are called byte 1. 
The value of the byte returned by IGTBYT is an integer value between 0 and 255. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

FINDCH - Searches a variable or an array for an occurrence of a character string 

SYNOPSIS 

CALL FMDCH(ckrsJen,strJs#b,ifnd) 

DESCRIPTION 

chrs Variable or array of any type or length containing the search string 

len Length of the search string in bytes (must be from 1 to 256). Specify an integer variable, 

expression, or constant 

str Variable or array of any type or length that is searched for a match with chrs 

Is Starting byte in the str string. Specify an integer variable, expression, or constant Bytes 

are numbered from 1, beginning at the leftmost byte position of str. 

nb Number of bytes to be searched Specify an integer variable, expression, or constant. 

ifnd Type integer result 

The result of this subroutine search is equal to the 1 -based byte index into the variable or array where 
the matching string was found, or equal to 0 if no matching string was found. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 



SR-0113 



10-3 



D 



KOMSTR(3COS) 



KOMSTR(3COS) 



NAME 

KOMSTR - Compares specified bytes between variables or arrays 
SYNOPSIS 

result^KOM^R(strl t bytel t num,str2J>yte2) 
DESCRIPTION 

result Type integer result indicating results of the comparison: 
= 0 strl = str2 
- 1 strl > strl 
»-l strl < strl 

strl Variable or array of any type or length containing the byte string to compare against the 

byte string in str2 

bytel Starting byte of strl. Specify an integer variable, expression, or constant greater than 0. In 
a Cray word, bytes are numbered from 1 to 8, from the leftmost byte to the rightmost byte. 

num An integer variable, expression, or constant that contains the number of bytes to compare; 
must be greater than 0. 

str2 Variable or array of any type or length containing the byte string to compare against the 

byte string in strl 

byte2 Starting byte of str2. Specify an integer variable, expression, or constant greater than 0. In 
a Cray word, bytes are numbered from 1 to 8, from the leftmost byte to the rightmost byte. 

KOMSTR performs an unsigned, twos complement compare of a specified number of bytes from one 
variable or array with a specified number of bytes from another variable or array. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

STRMOV, MOVBIT - Moves bytes or bits from one variable or array to another 

SNYOPSIS 

CALL STRMOY(srcJsbsium,dest t idb) 
CALL MOVBlT($rc,i$b t nurn,dest t idb) 

DESCRIPTION 

src Variable or array of any type or length containing the bytes or string of bits to be moved. 

Bytes are numbered from 1, beginning at the leftmost byte position of src. 

isb Starting byte or bit in the src string. Specify an integer variable, expression, or constant 

greater than 0. Bytes and bits are numbered from 1, beginning at the leftmost byte or bit 
position of src. 

num An integer variable, expression, or constant that contains the number of bytes or bits to be 

moved; must be greater than 0. 

dest Variable or array of any type or length that contains the starting byte or bit to receive the 

data. Bytes and bits are numbered from 1, beginning at the leftmost byte or bit position of 
dest. 

idb An integer variable, expression, or constant that contains the starting byte or bit to receive 

the data; must be greater than 0. Bytes and bits are numbered from 1, beginning at the left- 
most byte or bit position of dest. 

STRMOV moves bytes from one variable or array to another. MOVBIT moves bits from one variable 
or array to another. 

CAUTION 

The argument dest must be declared long enough to hold num bytes, or a spill occurs and data is des- 
troyed. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

MVC - Moves characters from one memory area to another 
SYNOPSIS 

CALL MVC(si J lt j 2 j2Jk) 
DESCRIPTION 



s x Word address of the source string 

ji Byte offset from the source string word address of the first byte of the source string (the 

high-order byte of the first word of the source string is byte 1) 

Sx Word address of the destination string 

j 2 Byte offset from the destination string word address of the first byte of the destination 

siring (the high-order byte of the first word of the destination string is byte 1) 

k Number of bytes to be moved 



Source and destination strings can occur on any byte boundary. The move is performed 1 character at a 
time from left to right The destination string can overlap the source string. 

EXAMPLE 

To copy the first byte of an array throughout the array, invoke the routine as follows: 

CALL MVC(ARRAY,1,ARRAY,2,K»1) 
where K is the length of the array in bytes. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

TRIMLEN - Returns the number of characters in a string 

SYNOPSIS 

INTEGER TRIMLEN 
num. = TRIMLENCrtring) 

DESCRIPTION 

num. An integer variable giving the number of characters, excluding trailing blanks, in string 
string A string variable 

This function is intended for use with WRITE statements or with the concatenation operator. If you use 
it on the right-hand side of an assignment statement, any trailing blanks are put back as they were. 

EXAMPLE 

The following are examples of typical use: 

WRITE<6,901) STRING( 1 : TRIMLEN( STRING) ) 
901 FORMAT ( ' The String is >',A, , <') 

This example writes the string with the < character against the last nonblank character in string A. 

NEW = STRING( 1 :TRIMLEN{ STRING)) // '<The end* 

In this example, the < is again butted up against the last significant character in STRING even though 
STRING may have trailing blanks. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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11. HEAP MANAGEMENT AND TABLE MANAGEMENT ROUTINES 



These routines allow you to manage a block of memory (the heap) within your job area and to manipu- 
late tables. 

The management routines are divided into two categories: heap management and table management 
Corresponding CAL routines are found in the System Library Reference Manual, publication SM-0114. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

HEAP MANAGEMENT ROUTINES 

Heap management routines provide dynamic storage allocations by managing a block of memory, called 
the heap, within your job area. Each job has its own heap. The functions of the heap management rou- 
tines include allocating a block of memory, returning a block of memory to the heap's list of available 
space, and changing the length of a block of memory. Heap managment routines may also move a heap 
block to a new location if there is no room to extend it, return part of the heap to the operating system, 
check the integrity of the heap, and report heap statistics. See the COS Reference Manual, publication 
SR-0011, and the Segment Loader (SEGLDR) and Id Reference Manual, publication SR-0066, for the 
location of the heap and a description of the parameters on the LDR control statement or the SEGLDR 
directive that affect the heap. 

The heap management routines keep various statistics on the use of the heap. These include values 
used to tune heap parameters specified on the LDR control statement or the SEGLDR directive and infor- 
mation used in debugging. 

The following table contains the purpose, name, and entry of each heap management routine. 



Heap Management Routines 


Purpose 


Name 


Entry 


Allocate a block of memory from the 
heap 


HPALLOC 


HPALLOC 


Check the integrity of the heap 


HPCHECK 


HPCHECK 


Extend a block or copy block 
contents into a larger block 


HPCLMOVE 


HPCLMOVE 


Return a block of memory to the heap 


HPDEALLC 


HPDEALLC 


Dump the address and size of each heap 
block 


HPDDMP 


HPDUMP 


Change the size of an allocated heap block 


HPNEWLEN 


HPNEWLEN 


Return an unused portion of the heap 
to the operating system 


HPSHRINK 


HPSHRINK 


Return the length of a heap block 


fflPLEN 


IHPLEN 


Return statistics about the heap 


IHPSTAT 


IHPSTAT 
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TABLE MANAGEMENT ROUTINES 

The following table contains the purpose, name, and entry of each Fortran-callable table management 
routine. 



Table Management Routines 


Purpose 


Name 


Heading 


Add a word to a table 


TMADW 


TMADW 


Report table management operation 
statistics 


TMAMU 


TMAMU 


Allocate table space 


TMATS 


TMATS 


Request additional memory 


TMMEM 


TMMEM 


Search the table with a mask to 
locate a field within an entry 


TMMSC 


TMMSC 


Move memory 


TMMVE 


TMMVE 


Preset table space 


TMPTS 


TMPTS 


Search the table with or without a 
mask to locate a field within an 
entry and an offset 


TMSRC 


TMSRC 


Search a vector table for the search argument 


TMVSC 


TMVSC 



The Job Communication Block (JCB) field JCHLM (COS only) defines the beginning address of the table 
area. 

You must provide two control information tables with corresponding CAL ENTRY pseudo-ops: the 
Table Base Address (BTAB) and Table Length Table (LTAB). Their formats are listed in the System 
Library Reference Manual, publication SM-0114. The Fortran-callable versions of these routines use 
default BTAB and LTAB definitions from a common area in the library. 

TMINIT initializes the table descriptor vector, BTAB, and zeros all elements of the table length vector, 
LTAB. You must preset each element of BTAB to contain the desired interspace value for the 
corresponding table; for instance, si in the following example determines the interspace value for table 
1. Interspace values determine how many words are added to a table when more room is needed for 
that table or for any table with a lower number. 

INTEGER BTAB(/i), LTAB(n) 
DATA BTAB Isl t s2 9 s3 t ... t snl 



CALL TMINIT 

After the call to TMINIT, BTAB should not be changed. The interspace values have been shifted 48 bits to 
the left, bits 16 through 39 contain the current size of each table, and the rightmost 24 bits contain the abso- 
lute address of each table's first word. LTAB is used only to pass new table lengths from the user to the 
Table Manager. 

You can use statements such as the following to access each table. In this example, TABLEi is accessed. 

EQUIVALENCE (BTAB(i), PTRi) 
INTEGER PTRi, TABLEi (0:0) 
POINTER (PTRi, TABLEi) 



TABLEi (subscript) = 
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TM COMMON BLOCK - The common block name TM is reserved for use by the Table Manager and must 
always contain 64 LTAB words. 

COMMON /TM/ BTAB(64), LTAB(64) 

ACCESSING TABLE MANAGER TABLES (ALTERNATE METHOD) - Blank common can be used in the 
customary way, but the last entry in it should be for a one-dimensional array declared to contain just 1 word. 
The name of this array is then used to access the tables, beginning immediately after the end of blank com- 
mon. 

COMMON // TABLES( 1 ) 



WARNING 

Under COS, the heap management and table management subroutines cannot be used in the same appli- 
cation, unless the heap is of fixed size and placed before blank common. This restriction does not 
apply to UNICOS. 

The following statement function extracts the rightmost 24 bits from a BTAB word and changes that 
value from an absolute address to a relative address or offset within the table area. Thus the result of 
BASE(N) is an index into TABLES(l), pointing to the first word currently allocated to table N. 

BASE(N) = (BTAB(N) .AND. 77777777B) - LOC(TABLES(l)) 

WRITE(6,101) TABN 

1 01 FORMAT ('0 Dump of table ' ,12,/) 
OFFSET = 0 

102 CONTINUE 

DO 103 1=1,4 

INTABLE = OFFSET .LT. LTAB (TABN) 
IF (INTABLE) THEN 

OCTAL(I) = TABLES(1+BASE(TABN) + OFFSET) 
ALPHA(I)=TABLES(1+BASE(TABN) + OFFSET) 
ELSE 

OCTAL© = 0 
ALPHA(I) = ' 
ENDIF 

OFFSET = OFFSET+l 

103 CONTINUE 

WRITE (6,104) OFFSET-4, OCTAL, ALPHA 

104 FORMAT (I6,2X,4(022,1X),4A8) 

INTABLE = OFFSET .LT. LTAB (TABN) 
IF (INTABLE) GO TO 102 
WRITE (6,105) 

105 FORMAT if) 
RETURN 
END 
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NAME 

HPALLOC - Allocates a block of memory from the heap 
SYNOPSIS 

CALL HPALLOC(addr t length t errcode,abort) 
DESCRIPTION 

addr First word address of the allocated block (output) 
length Number of wonls of memory requested (input) 

errcode Error code. 0 if no error was detected; otherwise, a negative integer code for the type of 
error (output). 

abort Abort code; nonzero requests abort on error; 0 requests an error code (input). 

Allocate routines search the linked list of available space for a block greater than or equal to the size 
requested. 

The length of an allocated block can be greater than the requested length because blocks smaller than 
the managed memory epsilon specified on the LDR control statement (or in a SEGLDR directive) are 
never left on the free space list. 

Error conditions are as follows: 

Error Code Condition 

-1 Length is not an integer greater than 0 

-2 No more memory is available from the system (checked if the 

the request cannot be satisfied from the available blocks 
on the heap) 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

HPCHECK - Checks the integrity of the heap 

SYNOPSIS 

CALL HPCHECK(.errcode) 

DESCRIPTION 

errcode Error code. 0 if no error was detected; otherwise, a negative integer code for the type of 



error (output). 



Each control word is examined to ensure that it has not been overwritten. 



Error conditions are as follows: 



Error Code 



Condition 



-5 



Bad control word for the allocated block 



•6 



Bad control word for the free block 



IMPLEMENTATION 



This routine is available to users of both the COS and UNICOS operating systems. 
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HPCLMOVE(3U) 



NAME 

HPCLMOVE - Extends a block or copies block contents into a larger block 
SYNOPSIS 

CALL HPCLMOVE(addr,tength t status,aborf) 
DESCRIPTION 



addr On entry, first word address of the block to change; on exit, the new address of the block if 
it was moved. 

length Requested new total length (input) 

status Status. 0 if the block was extended in place; 1 if it was moved; a negative integer for the 
type of error detected (output). 

abort Abort code. Nonzero requests abort on error; 0 requests an error code (input). 



Change length and move routines extend a block if it is followed by a large enough free block or copy 
the contents of the existing block to a larger block and return a status code indicating that the block has 
been moved. These routines can also reduce the size of a block if the new length is less than the old 
length. In this case, they have the same effect as the change length routines. 

The new length of the block can be greater than the requested length because blocks smaller than the 
managed memory epsilon specified on the LDR control statement are never left on the free space list. 

Error conditions are as follows: 



Error Code Condition 

•1 Length is not an integer greater than 0 

-2 No more memory is available from the system (checked if the 

block cannot be extended and the free space list does not 
include a large enough block) 

-3 Address is outside the bounds of the heap 

-4 Block is already free 

-5 Address is not at the beginning of the block 

-7 Control word for the next block has been overwritten 

IMPLEMENTATION 



This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

HPDEALLC - Returns a block of memory to the list of available space (the heap) 

SYNOPSIS 

CALL HVDEALLC(addr t errcode t abort) 

DESCRIPTION 

addr First word address of the block to deallocate (input) 

errcode Error code. 0 if no eiror was detected; otherwise, a negative integer code for the type of 
error (output). 

abort Abort code. Nonzero requests abort on error; 0 requests an error code (input). 

Error conditions are as follows: 

Error Code Condition 

-3 Address is outside the bounds of the heap 

-4 Block is already free 

•5 Address is not at the beginning of the block 

-7 Control word for the next block has been overwritten 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 



HPDUMP - Dumps the address and size of each heap block 



SYNOPSIS 



CALL HPDUMP(code r dsname) 



DESCRIPTION 



code 



Code for the type of dump requested, as follows: 



Code 



Meaning 



0 
1 
2 
3 



Print heap statistics 



Dump all heap blocks in storage order 
Dump free blocks; follow NEXT links. 
Dump free blocks; follow PREY links. 



dsname Name of the dataset to which the dump is to be written, dsname must be in left-justified, 



Three types of dump are available: a dump of all heap blocks; a dump of free blocks that traces the 
links to the next block on the free list; and a dump of free blocks that traces the links to the previous 
block on the free list The dump stops if a recognizably invalid value is found in a field needed to con- 
tinue the dump. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 



SR-0113 11-8 D 



Hollerith form. 



HPNEWLEN ( 3U ) 



HPNEWLEN ( 3U ) 



NAME 

HPNEWLEN - Changes the size of an allocated heap block 
SYNOPSIS 

CALL HPNEWLEN(addrJength f status t abort) 
DESCRIPTION 



addr First word address of the block to change (input) 
length Requested new total length of the block (input) 

status Status. 0 if the change in length was successful; 1 if the block could not be extended in 
place; a negative integer for the type of error detected (output). 

abort Abort code. Nonzero requests abort on error; 0 requests an error code (input). 



Set new length routines change the size of an allocated heap block. If the new length is less than the 
allocated length, the portion starting at ADDR+LENGTH is returned to the heap. If the new length is 
greater than the allocated length, the block is extended if it is followed by a free block. A status is 
returned, telling whether the change was successful. 

The new length of the block can be greater than the requested length because blocks smaller than the 
managed memory epsilon specified on the LDR or SEGLDR control statement are never left on the free 
space list. 

Error conditions are as follows: 



Error Code Condition 

•1 Length is not an integer greater than 0 

-3 Address is outside the bounds of the heap 

-4 Block is already free 

-5 Address is not at the beginning of the block 

-7 Control word for the next block has been overwritten 

IMPLEMENTATION 



This routine is available to users of both the COS and UNICOS operating systems. 
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HPSHRINK (3U) 



NAME 

HPSHRINK - Returns an unused portion of heap to the operating system 

SYNOPSIS 

CALL HPSHRINK 

DESCRIPTION 

The unused portion of the heap is returned to the operating system only if the blocks closest to HLM 
(COS only) are free; no allocated blocks are moved. The minimum amount of memory to be returned is 
the managed memory increment specified on the LDR or SEGLDR control statement. These routines are 
called only from the user program. 

IMPLEMENTATION 

This routine is available only to the users of the COS operating system. 
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fflPLEN(3U) 



NAME 

fflPLEN - Returns the length of a heap block 

SYNOPSIS 

te/ig/A=IHPLEN (addr 9 errcode,abort) 

DESCRIPTION 

length Length of the block starting at addr (output) 
addr First word address of the block (input) 

encode Error code. 0 if no error was detected; otherwise, a negative integer code for the type of 
error (output). 

abort Abort code. Nonzero requests abort on error; 0 requests an error code (input). 

The length of the block can be greater than the amount requested because of the managed memory 
epsilon. 

Error conditions are as follows: 

Error Code Condition 

-3 Address is outside the bounds of the heap 

-4 Block is already free 

-5 Address is not at the beginning of the block 

-7 Control word for the next block has been overwritten 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

IHPSTAT - Returns statistics about the heap 

SYNOPSIS 

va/tte=IHPSTAT(c«fe) 

DESCRIPTION 

value Requested information 

code Code for the type of information requested, as follows: 



Code 


Meaning 


1 


Current heap length 


2 


Largest size of the heap so far 


3 


Smallest size of the heap so far 


4 


Number of allocated blocks 


5 


Number of times the heap has grown 


6 


Number of times the heap has shrunk 


7 


Last routine that changed the heap 


8 


Caller of the last routine that changed the heap 


9 


First word address of the heap area changed last 


10 


Size of the largest free block 


11 


Amount by which the heap can shrink 


12 


Amount by which the heap can grow 


13 


First word address of the heap 


14 


Last word address of the heap 



IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

TMADW - Adds a word to a table 

SYNOPSIS 

index=TMAD\V(number,entry) 

DESCRIPTION 

index Index of the added word 
number Table number 
entry Entry for the table 

IMPLEMENTATION 

This routine is available to the users of both the COS and UNICOS operating systems. 
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NAME 

TMAMU - Reports table management operation statistics 
SYNOPSIS 

CALL TMAMU(/en jabnumjabmovjabmar^word) 

DESCRIPTION 

len Allocated length of the table 

tabnum Number of tables used 

tabmov Number of table moves 

tabmar Maximum amount of memory used throughout the Table Manager 

nword Number of words moved 

IMPLEMENTATION 

This routine is available to the users of both the COS and UNICOS operating systems. 
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TMATS(3U) 



NAME 

TMATS - Allocates table space 

SYNOPSIS 

index=TMAJS(number,incre) 

DESCRIPTION 

index Index of the specified change 
number Table number 
incre Table increment 

IMPLEMENTATION 

This routine is available to the users of both the COS and UNICOS operating systems. 



SR-0I13 



11-15 



D 



TMMEM(3U) 
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NAME 

TMMEM - Requests additional memory 

SYNOPSIS 

CALL TMMEM(mem) 

DESCRIPTION 

mem Length of memory requested 

Upon exit, memory is extended by the requested amount No value is returned. 
IMPLEMENTATION 

This routine is available to the users of both the COS and UNICOS operating systems. 
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NAME 

TMMSC - Searches the table with a mask to locate a specific field within an entry 
SYNOPSIS 

index=TMMSC(tabnum,mask f sword>nword) 
DESCRIPTION 

index Table index of the match, if found; -1 if no match is found. 

tabnum Table number 

mask Mask defining a field within a word 

sword Search word 

nword Number of words per entry group 

IMPLEMENTATION 

This routine is available to the users of both the COS and UNICOS operating systems. 
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NAME 

TMMVE - Moves memory (words) 

SYNOPSIS 

CALL TMMVEtfrom Jo, count) 

DESCRIPTION 

from Address from which words are to be moved 

to Address of the location to which words are to be moved 

count Number of words to be moved 

IMPLEMENTATION 

This routine is available to the users of both the COS and UNICOS operating systems. 
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NAME 

TMPTS - Presets table space 

SYNOPSIS 

CALL TM?TS(start t len,preset) 

DESCRIPTION 

start Starting address 
len Length to preset 

preset Preset value; default is 0. 

IMPLEMENTATION 

This routine is available to the users of both the COS and UNICOS operating systems. 
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NAME 

TMSRC - Searches the table with an optional mask to locate a specific field within an entry and an 
offset 

SYNOPSIS 

index=TMSRC(tabnum t arg,nword,offset t mask) 
DESCRIPTION 

index Table index of the match, if a match is found; -1 if no match is found. 

tabnum Table number to search 

org Search argument or key 

nword Number of words per entry 

offset Offset into the entry group 

mask Field being searched for within an entry 

IMPLEMENTATION 

This routine is available to the users of both the COS and UNICOS operating systems. 
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TMVSC(3U) 



NAME 

TMVSC - Searches a vector table for the search argument 

SYNOPSIS 

index^TMVSC(tabnion i arg,nword) 

DESCRIPTION 

index Table index of the match, if found; -1 if no match is found. 

tabnum Table number 

org Search argument 

nword Number of words per entry group 

IMPLEMENTATION 

This routine is available to the users of bom the COS and UNICOS operating systems. 



SR-0113 



11-21 



D 



INTR0(3X) 



INTRO(3X) 



12. I/O ROUTINES 



The I/O routines include the following: 

• Dataset positioning routines 

• Auxiliary NAMELIST routines 

• Logical record I/O routines 

• Random access dataset I/O routines 

• Asynchronous queued I/O routines 

• Output suppression routines 

• Fortran-callable tape routines involving beginning- and end-of-volume processing 

DATASET POSITIONING ROUTINES 

Dataset positioning routines change or indicate the position of the current dataset These routines set the 
current positioning direction to input (read). If the previous processing direction is output (write), end- 
of-data is written on a blocked sequential dataset, and the buffer is flushed. On a random dataset, the 
buffer is flushed. 

The following table contains the name, purpose* and entry of each dataset positioning routine. 



Dataset Positioning Routines 


Purpose 


Name 


Entry 


Receive position information about 
an opened tape dataset 


GETTP 


GETTP 


Position a specified tape dataset at 
a tape block 


SETTP 


SETTP 


Synchronize the specified program and an 
opened tape dataset 


SYNCH 


SYNCH 


Return current position of an interchange 
tape or mass storage dataset 


GETPOS 


GETPOS 


Return to the position retained from 
the GETPOS request 


SETPOS 
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AUXILIARY NAMELIST ROUTINES 

NAMELIST routines allow you to control input and output defaults and are accessed by call-by-address 
subprogram linkage. No arguments are returned. For a more complete description of the NAMELIST 
feature, see the Fortran (CFT) Reference Manual, publication SR-0009 or the CFT77 Reference Manual, 
publication SR-0018. 

The following table contains the purpose, name, and entry of each auxiliary NAMELIST routine. 



Auxiliary NAMELIST Routines 


Purpose 


Name 


Entry 


Delete or add a trailing comment 
indicator 


RNLCOMM 


RNL 


Delete or add a delimiting character 


RNLDELM 


Delete or add an echo character 


RNLFLAG 


Delete or add a replacement character 


RNLREP 


Delete or add a separator character 


RNLSEP 


Specify the output unit for error 
messages and echo lines 


RNLECHO 


RNLECHO 


Take action when an undesired 
NAMELIST group is encountered 


RNLSKIP 


RNLSKIP 


Determine the action if a type mismatch 
occurs across the equal sign on an 
input record 


RNLTYPE 


RNLTYPE 


Define an ASCII NAMELIST delimiter 


WNLDELM 


WNL 


Indicate the first ASCII character 
of the first line 


WNLFLAG 


Define ASCII NAMELIST replacement 
character 


WNLREP 


Define ASCII NAMELIST separator 


WNLSEP 


Allow each NAMELIST variable to 
begin on a new line 


WNLLINE 


WNLLINE 


Indicate output line length 


WNLLONG 


WNLLONG 
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LOGICAL RECORD I/O ROUTINES 

The logical record I/O routines are divided into read routines, write routines, and bad data error 
recovery routines. The following table contains the purpose, name, and entry of each logical record I/O 
routine. 



Logical Record I/O Routines 


Purpose 


Name 


Entry 


Read words, full record mode 


READ 


READ 


Read words, partial record mode 


READP 


Read characters, full record mode 


READC 


READC 


Read characters, partial record mode 


READCP 


Read two IBM 32-bit floating-point 
words from each Cray 64-bit word 


READIBM 


READIBM 


Write words, fall record mode 


WRITE 


WRITE 


Write words, partial record mode 


WRITEP 


Write characters, full record mode 


WRTTEC 


WRITEC 


Write characters, partial record mode 


WRITECP 


Write two IBM 32-bit floating-point 
words from each Cray 64-bit word 


WRITIBM 


WRITIBM 


Skip bad data 


SKIPBAD 


SKIPBAD 


Make bad data available 


ACPTBAD 


ACPTBAD 



READ ROUTINES - Read routines transfer partial or full records of data from the VO buffer to the user 
data area Depending on the read request issued, the data is placed in the user data area either 1 char- 
acter per word or in full words. (Blank decompression occurs only when data is being read 1 character 
per word.) In partial mode, the dataset maintains its position after the read is executed. In record 
mode, the dataset position is maintained after the end-of-iecord (EOR) that terminates the current 
record 

WRITE ROUTINES - Write routines transfer partial or full records of data from the user data area to 
the I/O buffer. Depending on the write operation requested, data either is taken from the user data area 
1 character per word and packed & characters per word or is transferred in full words. In partial mode, 
no end-of-record (EOR) is inserted in the I/O buffer in the word following the data that terminates the 
record. 

BAD DATA ERROR RECOVERY ROUTINES - Bad data error recovery routines enable a user program 
to continue processing a dataset when bad data is encountered. "Bad data n refers to an unrecovered 
error encountered while the dataset was being read. Skipping the data forces the dataset to a position 
past the bad data, so that no data is transferred to the user-specified buffer. Accepting the data causes 
the bad data to be transferred to a user-specified buffer. The dataset is then positioned immediately fol- 
lowing the bad data. 

When an unrecovered data error is encountered, continue processing by calling either the SKIPBAD or 
the ACPTBAD routine. 
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RANDOM ACCESS DATASET I/O ROUTINES 

Sequentially accessed datasets are used for applications that read input only once during a process and 
write output only once during a process. However, when large numbers of intermediate results are used 
randomly as input at different stages of jobs, a random access dataset capability is more efficient than 
sequential access. A random access dataset consists of records that are accessed and changed. Random 
access of data eliminates the slow processing and inconvenience of sequential access when the order of 
reading and writing records differs in various applications. 

Random access dataset I/O routines allow you to specify how records of a dataset are to be changed, 
without the usual limitations of sequential access. Choose specific routines based on performance 
requirements and the type of access needed. 

Random access datasets can be created and accessed by the record-addressable, random access dataset 
routines (READMS/WRTTMS, and READDRAVRTTDR) or the word-addressable, random access dataset 
routines (GETWA/PUTWA). 

NOTE - Generally, random access dataset I/O routines used in a program with overlays or segments 
should reside in the first overlay or root segment. However, if all I/O is done within one overlay or 
segment, the routines can reside in that overlay. If all I/O is done in an overlay's successor, the rou- 
tines can reside in the successor overlay. 

RECORD-ADDRESSABLE, RANDOM ACCESS DATASET I/O ROUTINES - Record-addressable, random 
access dataset I/O routines allow you to generate datasets containing variable-length, individually 
addressable records. These records can be read and rewritten at your discretion. The library routines 
update indexes and pointers. The random access dataset information is stored in two places: in an array 
in user memory and at the end of the random access dataset. 

When a random access dataset is opened, an array in user memory contains the master index to the 
records of the dataset This master index contains the pointers to and, optionally, the names of the 
records within the dataset. Although you provide this storage area, it must be modified only by the ran- 
dom access dataset I/O routines. 

When a random access dataset is closed and optionally saved, the storage area containing the master 
index is mapped to the end of the random access dataset, thus recording changes to the contents of the 
dataset. 

The following Fortran-callable routines can change or access a record-addressable, random access 
dataset: OPENMS, WRITMS, READMS, CLOSMS, FINDMS, CHECKMS, WAITMS, ASYNCMS, 
SYNCMS, OPENDR, WRITDR, READDR, CLOSDR, STINDR, CHECKDR, WAITDR, ASYNCDR, 
SYNCDR, and STINDX. 

The READDRAVRTTDR random access I/O routines are direct-to-disk versions of RE ADM S/WRTTM S . 
All input or output goes directly between the user data area and the mass storage dataset without pass- 
ing through a system -maintained buffer. Because mass storage can only be addressed in 5 12- word 
blocks, all record lengths are rounded up to the next multiple of 512 words. 

You can intermix READMS/WRITMS and READDR/WRITDR datasets in the same program, but you 
must not use the same file in both packages simultaneously. 

OPENMS/OPENDR opens a local dataset and specifies the dataset as a random access dataset that can 
be accessed or changed by the record-addressable, random access dataset I/O routines. If the dataset 
does not exist, the master index contains zeros; if the dataset does exist, the master index is read from 
the dataset. The master index contains the current index to the dataset The current index is updated 
when the dataset is closed using CLOSMS/CLOSDR. 
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A single job can use up to 40 active READMS/WRITMS files and 20 READDRAVRITDR files. 

The following table contains the name, purpose, and entry of each record-addressable, random access 
dataset I/O routine. 



Record-addressable, Random Access Dataset I/O Routines 


Purpose 


Name 


Entry 


Set the I/O mode to be asynchronous 


ASYNCMS 
ASYNCDR 


ASYNCMS 


Check the status of an asynchronous I/O 
operation 


tnLCKMb 
CHECKDR 


LHECKMS 


\_,iose a random access oaiasei ana wnie 
the master index 


CLOSDR 




Read records into data buffers used by 
random access dataset routines 


FINDMS 


FINDMS 


Open a local dataset as a random access 
dataset 


OPENMS 
OPENDR 


OPENMS 


Allow an index to be used as the current index 
by creating a subindex 


STINDX 
STINDR 


STINDX 


Set the I/O mode to be synchronous 


SYNCMS 
SYNCDR 


SYNCMS 


Wait for completion of an asynchronous I/O 
operation 


WAITMS 
WAITDR 


WAITMS 


Write data from user memory to a random 
access dataset and update the index 


WRITMS 
WRITDR 


WRITMS 



WORD -ADDRESSABLE, RANDOM ACCESS DATASET I/O ROUTINES - A word-addressable, random 
access dataset consists of an adjustable number of contiguous words. You can access any word or con- 
tiguous sequence of words from a word-addressable, random access dataset by using the associated rou- 
tines. These datasets and their I/O routines are similar to the record-addressable, random access datasets 
and their routines. The Fortran-callable, word-addressable random access I/O routines are: 

COS and UNTCOS: WOPEN, WCLOSE, PUTWA, APUTWA, GETWA, and SEEK. 
COS only: WOPENU, WCLOSEU, PUTWAU, GETWAU, and WCHECK. 

WOPEN opens a dataset and specifies it as a word-addressable, random access dataset that can be 
accessed or changed with the word-addressable routines. The WOPEN call is optional. If a call to 
GETWA or PUTWA is executed first, the dataset is opened for you with the default number of blocks 
(16) t and istats is turned on. 

The following table contains the purpose, name, and entry of each word-addressable, random access 
dataset I/O routine. 
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Word-addressable, Random Access Dataset I/O Routines 


Purpose 


Name 


Entry 


Synchronously read words from the 
dataset into user memory 


GETWA 


GETWA 


SVSynCiirOIlUUaiy icau U&la JJ1LU 

dataset buffers 




Asyncnronuusiy reau worus iruin 
disk, directly to user 




Vj.I1* 1 WAU 


Synchronously write words from 
memorv to the dataset 


PUTWA 


PUTWA 


Asynchronously write words from 
memory to the dataset 


APUTWA 


Asynchronously write words from 
memory to the unbuffered dataset 


PUTWAU 


PUTWAU 


Checks word-addressable file status 


WCHECK 


WCHECK 


Finalize additions and changes 
and close the dataset 


WCLOSE 


WCLOSE 


Finalize additions and changes 
and close the unbuffered dataset 


WCLOSEU 


WCLOSEU 


Open a dataset and specify it as 
word-addressable, random access 


WOPEN 


WOPEN 


Open an unbuffered dataset and specify 
it as word-addressable, random access 


WOPENU 


WOPENU 



ASYNCHRONOUS QUEUED I/O ROUTINES 

Asynchronous queued I/O (AQIO) routines initiate a transfer of data and allow the subsequent execution 
sequence to proceed concurrently with the actual transfer. 

These routines allow programmers to create a queue of I/O requests to a single-user dataset. Program- 
mers can issue several I/O requests to a given dataset without having to manage the busy status of the 
dataset. By allowing the queue to build up before issuing an I/O request, AQIO routines prevent the 
normal job abort that occurs when an I/O request is issued while another I/O request is still active. In 
addition, AQIO routines allow increased performance over other I/O methods. 

The following table contains the purpose, name, and entry of each asynchronous queued I/O routine. 
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Asynchronous Queued I/O Routines 



Purpose 


Name 


Entry 


Close an asynchronous queued I/O 
dataset or file 


AQCLOSE 


AQCLOSE 


Open a dataset or file for 

fl^vnrhrnnnni nnpiifirt T/O 

AgyilwlUvllvUiS UyvUvil' Af\*f 


AQOPEN 


AQOPEN 


Open a dataset or file for 
asynchronous queued I/O, allowing 
user to specify dataset size 
and location 


AQOPENDV 


AQOPENDV 


Queue a simple asynchronous I/O 
read request 


AQREAD 


AQREAD 


Queue a compound asynchronous I/O 
read request 


AQREADC 


Queue a compound read request 
with the ignore bit set 


AQREADCI 


Queue a simple read request with the ignore 
bit set 


AQREADI 


Prevent a segment of I/O and part of 
the program from executing concurrently 
(used with AQRIR) 


AQRECALL 


AQRECALL 


Designate point in I/O at which 
concurrent processing can resume 
(used with AQRECALL) 


AQRIR 


Check the status of asynchronous queued 
I/O requests 


AQSTAT 


AQSTAT 


Queue a stop request in the asyncronous 
queued I/O buffer 


AQSTOP 


AQSTOP 


Queue a synchronization request in the 
asynchronous queued I/O buffer 


AQSYNC 


AQSYNC 


Wait for completion of asynchronous 
queued I/O requests 


AQWATT 


AQWAIT 


Queue a simple asynchronous I/O 
write request 


AQWRITE 


AQWRITE 


Queue a compound asynchronous I/O 
write request 


AQWR1TEC 


Queue a compound write request with 
bit set 


AQWRTTEC 


Queue a write request with the ignore 
bit set 


AQWRITEI 
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OUTPUT SUPPRESSION ROUTINES 

Output suppression routines are special-purpose routines designed to output blank values in Fortran pro- 
grams. 

FSUP and FSUPC turn suppression on and off for the following Fortran edit descriptors: F-type, G-type, 
and E-type. 

ISUP and ISUPC turn suppression on and off for the Fortran edit descriptor I-type. 
AH of these routines are described under the FSUP entry. 

BOV/EOV FORTRAN-CALLABLE ROUTINES 

Fortran-callable routines are designed to perform special functions on a tape dataset, such as 
beginning-of-volume (BOV) and end-of-volume (EOV) processing. 

The following tables contain the purpose, name, and entry of each BOV/EOV Fortran-callable routine. 
Cray Research highly recommends using the first set of routines, STARTSP, SETSP, CLOSEV, and 
ENDSP. 



BOV/EOV Fortran-callable Routines (New Routines) 


Purpose 


Name 


Entry 


Switch tape volumes 


CLOSKV 


CLOSEV 


End special EOV/BOV processing 


ENDSP 


ENDSP 


Request notification at end of tape volume 


SETSP 


SETSP 


Begin tape BOV/EOV processing 


STARTSP 


STARTSP 



BOV/EOV Fortran-callable Routines (Obsolete Routines) 



Purpose 


Name 


Entry 


Check tape I/O status 


CHECKTP 


CHECKTP 


Continue normal I/O operation 


CONTPIO 


CONTPIO 


Begin special processing at 
BOV 


PROCBOV 


PROCBOV 


Begin special processing at 
EOV 


PROCEOV 


PROCEOV 


Switch tape volume 


SWTTCHV 


SWITCH V 


Initialize/terminate special 
BOV/EOV processing 


SVOLPRC 


SVOLPRC 



SR-0113 



12-8 



D 



ACPTBAD(3IO) 



ACPTBAD(3IO) 



NAME 

ACPTBAD - Makes bad data available 
SYNOPSIS 

CALL ACPTBAI)(dn,uda f wrdcnt,termend t uhcnt) 

DESCRIPTION 

dn Dataset name or unit number 

uda User data area to receive the bad data 

wrdcnt On exit, number of words transferred 

termcnd On exit, address of termination condition 
=0 Positioned at end-of-block 
=1 Positioned at end-of-file 
=2 Positioned at end-of-data 
<0 Not positioned at end-of-block 

ubcnt On exit, address of unused bit count. Only defined if termcnd is 0, and wrdcnt is nonzero. 
ACPTBAD makes bad data available to you by transferring it to the user-specified buffer. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

EXAMPLE 
C 

PROGRAM EXAMPLE1 
IMPLICIT INTEGER(A-Z) 
REAL UNIT, UNTTSTAT 

PARAMETER(NBYTES=400000J^DIM=NBYTES/8 t DN=99) 
DIMENSION B UFFER( 1 ;NDIM) 
DIMENSION UDA(1:512) 

2000 CONTINUE 

NWORDS = NDIM 

CALL READ(DN,BUFFER > NWORDS f STATUS) 
UNTTSTAT = UNTT(DN) 

IF(STATUS.EQ.4 ,OR. UNITSTAT.GT.0.0) THEN IParity error 
3000 CONTINUE 

CALL ACPTBADO>N f UDA,WC f TERMCND f UBCNT) 

C — >Build up user record: 
K = 0 

DO 3500 I=(NWORDS -»- 1). (NWORDS + WC), 1 
K=DC + 1 
BUFFER(I) = UDA(K) 
3500 CONTINUE 
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IF(TERMCND.LT.O) THEN 
GO TO 3000 
ENDIF 
EKDIF 

STOP 'COMPLETE* 
END 

SEE ALSO 

SKIPBAD 
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NAME 

AQCLOSE - Closes an asynchronous queued I/O dataset or file 

SYNOPSIS 

CALL AQCLOSE(aqp,status) 

DESCRIPTION 

aqp Type INTEGER array. The name of the array in the user's program that contains the asyn- 

chronous queued I/O parameter block. This must be the same array specified in the 
AQOPEN request. 

status Type INTEGER variable. Status code; status returns any errors or status information to the 
user. On output from AQCLOSE, status has one of the following values: 
>0 Information only 
=0 No error delected 
<0 Error detected 



Status Codes 


0 


No errors detected 


+1 


The asynchronous queued I/O parameter block is full 


+2 


No I/O is active on the asynchronous queued I/O dataset or file 


+3 


Asynchronous queued I/O request is stuck 


+4 


The asynchronous request is queued for I/O 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems, 

SEE ALSO 

AQOPEN, AQREAD, AQREADC, AQSTAT, AQWAIT, AQWRITE, AQWRTTEC 
The AQIO User's Guide, publication SN-0247 
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NAME 

AQOPEN - Opens a dataset or file for asynchronous queued I/O 

SYNOPSIS 

CALL AQOPEN(aqp,aqpshe f dn,status) 



DESCRIPTION 
aqp 

aqpsize 



dn 



status 



Type INTEGER array. The name of the array in the user's program that will contain the 
asynchronous queued I/O. 

Type INTEGER variable, expression, or constant. The length of the asynchronous queued 
I/O parameter block. Each queued I/O entry in the parameter block is 8 words long. The 
array aqp must contain at least 1 entry plus 32 words for dataset definitions. Therefore, 
aqpsize should be 32 + 8n; n is the number of user-specified asynchronous queued I/O 
entries in the parameter block, and n > 3. 

Type INTEGER variable, expression, or constant. The name of the dataset as a Hollerith 
constant or the unit number of the dataset 

Type INTEGER variable. Status code status returns any errors or status information to the 
user. On output from AQOPEN, status has one of the following values: 



>0 Information only 
=0 No errors detected 
<0 Error detected 



Status Codes 


0 


No errors detected 


+1 


The asynchronous queued I/O parameter block is full 


+2 


No I/O is active on the asynchronous queued I/O dataset or file 


+3 


The asynchronous queued I/O request is stuck 


+4 


The asynchronous request is queued for I/O 


-1 


Illegal aqpsize on the AQOPEN request Minimum size 
is equal to 32 + 8n, where n > 3. 



Asynchronous queued I/O provides a method of random access to or from mass storage into buffers in 
user memory. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems, 

NOTES 

A file opened using AQOPEN should only be closed by AQCLOSE or by job step advance. If you close 
the file in some other way, the subsequent behavior of the program is unpredictable. Among these 
other ways are explicit methods of closing the file (for example, CLOS and CALL RELEASE) and 
implicit methods (such as CALL SAVE). 

SEE ALSO 

AQREAD, AQREADC, AQWRITE, AQWRITEC, AQCLOSE, AQWAIT, AQSTAT 
The AQIO User's Guide, SN-0247 
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NAME 

AQOPENDV - Opens a dataset or file for asynchronous queued I/O, allowing user to specify dataset size 
and physical location 

SYNOPSIS 

CALL AQQPENT)\(aqp t aqpsize t dn>pdv t plength t status) 
DESCRIPTION 

aqp Type INTEGER array. The name of the array in the user's program that will contain the 

asynchronous queued I/O. 

aqpsize Type INTEGER variable, expression, or constant The length of the asynchronous queued 
I/O parameter block. Each queued I/O entry in the parameter block is 8 words long. The 
array aqp must contain at least 1 entry plus 32 words for dataset definitions. Therefore, 
aqpsize should be 32 + %n\ n is the number of user-specified asynchronous queued I/O 
entries in the parameter block, and n > 3. 

dn Type INTEGER variable, expression, or constant The name of the dataset as a Hollerith 

constant or the unit number of the dataset 

pdv Name of a specific device on which the asynchronous queued I/O dataset is to reside, such 

as SSD-0-20. 

plength Minimum desired length of the asynchronous queued I/O dataset (in 5 12- word blocks), to 
be set upon initialization. If plength ~ 0, this routine will operate the same as AQOPEN. 

status Type INTEGER variable. Status code status returns any errors or status information to the 
user. On output from AQOPENDV, status has one of the following values: 



>0 Information only 
=0 No errors detected 
<0 Error detected 



Status Codes 


0 


No errors detected 


+1 


The asynchronous queued I/O parameter block is full 


+2 


No I/O is active on the asynchronous queued I/O dataset or file 


+3 


The asynchronous queued I/O request is stuck 


+4 


The asynchronous request is queued for I/O 


-1 


Illegal aqpsize on the AQOPENDV request Minimum size 
is equal to 32 + 8/i, where n > 3. 



Asynchronous queued I/O provides a method of random access to or from mass storage into buffers in 
user memory. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTES 

A file opened using AQOPENDV should only be closed by AQCLOSE or by job step advance. If you 
close the file in some other way, the subsequent behavior of the program is unpredictable. Among 
these other ways are explicit methods of closing the file (for example, CLOS and CALL RELEASE) and 
implicit methods (such as CALL SAVE). 
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SEE ALSO 



AQOPEN, AQREAD, AQREADC, AQWRTTE, AQWRITEC, AQCLOSE, AQWATT, AQSTAT 
The AQIO User's Guide, SN-0247 
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NAME 

AQREAD, AQREADC, AQREADI, AQREADCI - Queues a simple or compound asynchronous I/O read 
request 

SYNOPSIS 

CALL AQREAD(aqpxpuaddMknum t blocks t reqid t queiie t status) 
CALL AQREADC(aqp t cpuadd,mstrideMknumMocks4strideMcs,reqid,qw 
CALL AQREADl(aqp t cpuaddMknum t bbcks l reqid t queue t status) 
CALL AQREAT)CI(aqp,cpuadd,mstrideMknumMocfo4strid£,ines t r^^ 

DESCRIPTION 

aqp Type INTEGER array. The name of the array in the user's program that contains the asyn- 

chronous queued I/O parameter block. Must be the same array as specified in the AQOPEN 
request 

cpuadd Type determined by user. Starting memory address; the location where the first word of 
data is placed. 

mstride Type INTEGER variable, expression, or constant Data buffer stride; the number of memory 
words to skip between the base addresses of consecutive transfers. The stride value may be 
positive (to skip forward), negative (to skip backward), or 0. This parameter is valid for 
compound read requests only. 

blknum Type INTEGER variable, expression, or constant. Starting block number. The block 
number of the first block to be read on this request. 

blocks Type INTEGER variable, expression, or constant The number of 512~word blocks to be 
read. 

dstride Type INTEGER variable, expression, or constant. Disk stride; the number of disk blocks to 
skip between the base addresses of consecutive transfers. The stride value may be positive 
(to skip forward), negative (to skip backward), or 0. This parameter is valid for compound 
requests only. 

incs Type INTEGER variable, expression, or constant The number of simple requests minus 1 

that comprise a compound request Zero (0) implies a simple request. This parameter is 
valid for compound requests only. 

reqid Type INTEGER variable, expression, or constant A user-supplied value for identifying a 
particular request. 

queue Type INTEGER variable, expression, or constant. Queue flag. If 0, VO is initiated provided 
that I/O on the dataset or file is not already active. If the queue flag is set to nonzero, the 
request is added to the queue but no attempt is made to start I/O. 

status Type INTEGER variable. Status code status returns any errors to the user. On output from 
these routines, status has one of the following values: 

>0 Information only 
=0 No error detected 
<0 Error detected 
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Status Codes 


0 


No errors detected 


+1 


The asynchronous queued I/O parameter block is full 


+2 


No I/O is active on the asynchronous queued VO dataset or file 


+3 


The asynchronous queued I/O request is stuck 


44 


The asynchronous request is queued for I/O 



AQREAD, AQREADC, AQREADI, and AQREADCI transfer data between the data buffer and the device 
on which the dataset or file resides. Requests may be simple (AQREAD and AQREADI) or compound 
(AQREADC and AQREADCI). A simple request is one in which data from consecutive sectors on the 
disk is read into one buffer. A compound request is one in which a number of simple requests are 
separated by a constant number of sectors on disk, or a constant number of memory words for buffers, 
or both. 

AQREADI and AQREADCI operate in the same fashion as AQREAD and AQREADC, respectively, 
except the ignore bit is set. The ignore bit tells the operating system not to change from write mode to 
process this read request* As an example, setting the ignore bit might be helpful on a system with two 
high-speed SSD channels. A series of AQWRITE calls followed by an AQREADI call would not force a 
wait by the operating system as would a normal read. 

IMPLEMENTATION 

AQREAD and AQREADC are available to users of both the COS and UNICOS operating systems. 
AQREADI and AQREADCI are available only to users of the COS operating system. 

SEE ALSO 

AQWRITE, AQWRITEC, AQCLOSE, AQWAIT, AQSTAT 
The AQIO User's Guide, SN-0247 
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NAME 

AQRECALL, AQRIR - Delays program execution during a queued I/O sequence 

SYNOPSIS 

CALL AQRECALL(aqp f status) 
CALL AQ RlR(aqp,reqid>queue status) 

DESCRIPTION 

aqp Type INTEGER array. The name of the array in the user's program that will contain the 

asynchronous queued I/O. 

reqid Type INTEGER variable, expression, or constant. A user-supplied value for identifying a 
particular request. 

queue Type INTEGER variable, expression, or constant. Queue flag. If 0, I/O is initiated provided 
that I/O on the dataset is not already active. If the queue flag is set to nonzero, the request 
is added to the queue but no attempt is made to start I/O. 

status Type INTEGER variable. Status code status returns any errors or status information to the 
user. On output from AQOPEN, status has one of the following values: 

>0 Information only 
=0 No errors detected 
<0 Error detected 



Status Codes 


0 


No errors detected 


+1 


The asynchronous queued I/O parameter block is full 


+3 


The asynchronous queued I/O request is stuck 



AQRECALL and AQRIR work together to let you suspend the execution of your program during part of 
an asynchronous queued I/O process. AQRIR marks the point in the I/O process up to which program 
execution is delayed, while AQRECALL marks the point in the program beyond which execution should 
not proceed until the specified I/O is complete. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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EXAMPLE 

J = 1 

DO I = 1,10 
1F(I.EQ10) J = 0 

CALL AQREAD(AQP,A,IBLOCK,10,U,ISTAT) 
BLOCK = IBLOCK + 10 

1 CONTINUE 

CALL AQRIR(AQP,0 0.ISTAT1) 
J = 1 

DO 2 I - 11,30 
IF(I.EQ.30) J = 0 

CALL AQREAD(AQPA,IBLOCK,10,U,ISTAT2) 
IBLOCK = IBLOCK + 10 

2 CONTINUE 

CALL AQRECALL(AQPJSTAT3) 

In the above example, 10 asynchronous reads are queued up, followed by an AQRIR. Any code beyond 
the AQRECALL call does not execute until the AQRIR request is encountered in the queue. When it is 
encountered, execution beyond AQRECALL continues. The following illustrates the queue containing 
the AQREAD requests and the AQRIR request. 



AQREAD 
AQREAD 



AQREAD 
AQRIR 



SEE ALSO 

AQREAD, AQREADC, AQWRITE, AQWRITEC, AQCLOSE, AQWAIT, AQSTAT 
The AQIO User's Guide, SN-0247 
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NAME 

AQSTAT - Checks the status of asynchronous queued I/O requests 

SYNOPSIS 

CALL AQSTAT(aqp t reply,reqid t status) 

DESCRIPTION 

aqp Type INTEGER array. The name of the array in the user's program that contains the asyn- 

chronous queued I/O parameter block. This must be the same array specified in the 
AQOPEN request. 

reply Type INTEGER variable 

reqid Type INTEGER variable, expression, or constant. If reqid is 0, AQSTAT returns the request 
ID of the next queued I/O request to be done. If reqid is nonzero, status information about 
the specified request ID will be returned. 

status Type INTEGER variable. Status code, status returns any errors or status information to the 
user. On output from AQSTAT: 

>0 Information only 
=0 No errors detected 
<0 Error detected 



Status Codes 


0 


No errors detected 


+1 


The asynchronous queued I/O parameter block is full 


+2 


No I/O is active on the asynchronous queued I/O dataset or file 


+3 


The asynchronous queued I/O request is stuck 


+4 


The asynchronous request is queued for I/O 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

AQOPEN, AQREAD, AQREADC, AQWRITE, AQWRTTEC, AQCLOSE, AQWAIT 
The AQIO User's Guide, SN-0247 
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NAME 

AQSTOP - Stops the processing of asynchronous queued I/O requests 

SYNOPSIS 

CALL AQSTOV(aqp t reqid t queue,status) 

DESCRIPTION 

aqp Type INTEGER array. The name of the array in the user's program that will contain the 

asynchronous queued I/O. 

reqid Type INTEGER variable, expression, or constant. A user-supplied value for identifying a 
particular request. 

queue Type INTEGER variable, expression, or constant. Queue flag. If 0, I/O is initiated provided 
that I/O on the dataset is not already active. If the queue flag is set to nonzero, the request 
is added to the queue but no attempt is made to start I/O. 

status Type INTEGER variable. Status code status returns any errors or status information to the 
user. On oulput from AQSTOP, status has one of the following values: 



>0 Information only 
=0 No errors detected 
<0 Error detected 



Status Codes 


0 


No errors detected 


+1 


The asynchronous queued I/O parameter block is full 


+2 


No I/O is active on the asynchronous queued I/O dataset or file 


+3 


The asynchronous queued I/O request is stuck 


44 


The asynchronous request is queued for I/O 



The AQSTOP routine stops the processing of a list of asynchronous I/O requests when it is encountered 
in the queue. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

AQREAD, AQWRITE, AQCLOSE, AQWATT, AQSTAT, AQRECALL, AQSYNC 
The AQIO User's Guide, SN-0247 



SR-0113 



12-20 



D 



AQWATT(3IO) 



AQWATT(3I0) 



NAME 

AQWAIT - Waits on a completion of asynchronous queued I/O requests 

SYNOPSIS 

CALL &QWATT(aqp,status) 

DESCRIPTION 

aqp Type INTEGER array. The name of the array in the user's program that contains the asyn- 

chronous queued I/O parameter block. This must be the same array specified in the 
AQOPEN request. 

status Type INTEGER variable. Status code status returns any errors or status information to the 
user. On output from AQWAIT status has one of the following values: 

>0 Information only 
=0 No errors detected 
<0 Error detected 



Status Codes 


0 


No errors detected 


+1 


The asynchronous queued I/O parameter block is full 


+2 


No I/O is active on the asynchronous queued I/O dataset or file 


+3 


The asynchronous queued I/O request is stuck 


+4 


The asynchronous request is queued for I/O 



AQWAIT leaves the job suspended until the entire request list is exhausted. 

IMPLEMENTATION 

This routine is available to users of both the COS and UN1COS operating systems. 

SEE ALSO 

AQOPEN, AQREAD, AQREADC, AQWRITE, AQWRITEC, AQCLOSE, AQSTAT 
The AQIO User's Guide, SN-0247 
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NAME 

AQWRTTE, AQWRJTEC, AQWRITEI, AQWRTECI - Queues a simple or compound asynchronous I/O 
write request 

SYNOPSIS 

CALL \QWBlTE{aqp t cpuaddMknum i blocks t reqid,queue .status) 
CALL &QyfVtITJLC(aqp,cpuadd t msfr^ 

CALL AQWRlTfll(aqp t cpuaddMknum f blocks,reqid f queue r status) 
CALL AQWRTECI(aqp,cpuadd,mstrideMknimMocks,& 

DESCRIPTION 

aqp Type INTEGER array. The name of the array in the user's program that contains the asyn- 

chronous queued I/O parameter block. Must be the same array specified in the AQOPEN 
request. 

cpuadd Type determined by user. Starting memory address; the location of the first word in the 
user's program to be written. 

mstride Type INTEGER variable, expression, or constant Data buffer stride; the number of memory 
words to skip between the base addresses of consecutive transfers. The stride value may be 
positive (to skip forward), negative (to skip backward), or 0. This parameter is valid for 
compound write requests only. 

blknwn Type INTEGER variable, expression, or constant. Starting block number; the block number 
of the first block to be written on this request. 

blocks Type INTEGER variable, expression, or constant The number of 5 12- word blocks to be 
written. 

dstride Type INTEGER variable, expression, or constant. Disk stride; the number of disk blocks to 
skip between the base addresses of consecutive transfers. The stride value may be positive 
(to skip forward), negative (to skip backward), or 0. This parameter is valid for compound 
requests only. 

incs Type INTEGER variable, expression, or constant. The number of simple requests minus 1 

that comprise a compound request Zero (0) implies a simple request. This parameter is 
valid for compound requests only. 

reqid Type INTEGER variable, expression, or constant A user-supplied value for identifying a 
particular request 

queue Type INTEGER variable, expression, or constant. Queue flag. If 0, I/O is initiated provided 
that I/O on the dataset or file is not already active. If the queue flag is set to nonzero, the 
request is added to the queue but no attempt is made to start I/O. 

status Type INTEGER variable. Status code status returns any errors to the user. On output from 
these routines, status has one of the following values: 

>0 Information only 
=0 No error detected 
<0 Error detected 
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Status Codes 


0 


No errors detected 


+1 


The asynchronous queued I/O parameter block is full 


+2 


No I/O is active on the asynchronous queued I/O dataset or file 


+3 


The asynchronous queued I/O request is stuck 


44 


The asynchronous request is queued for I/O 



AQWRITE, AQWRITEC, AQWRITEI, and AQWRTECI transfer data between the device on which the 
dataset or file resides and the data buffer. Requests may be simple (AQWRITE and AQWRITEI) or 
compound (AQWRITEC and AQWRTECI). A simple request is one in which data from one buffer is 
written to consecutive sectors on disk, A compound request is one in which a number of simple 
requests are separated by a constant number of sectors on disk, a constant number of memory words for 
buffers, or both. 

AQWRITEI and AQWRTECI operate in the same fashion as AQWRITE and AQWRITEC, respectively, 
except the ignore bit is set. The ignore bit tells the operating system not to change from read mode to 
process this write request. As an example, setting the ignore bit might be helpful on a system with two 
high-speed SSD channels. A series of AQREAD calls followed by an AQWRITEI call would not force a 
wait by the operating system as would a normal write. 

IMPLEMENTATION 

AQWRITE and AQWRITEC are available to users of both the COS and UNICOS operating systems. 
AQWRITEI and AQWRTTECI are available only to users of the COS operating system. 

SEE ALSO 

AQOPEN, AQREAD, AQREADC, AQCLOSE, AQWAIT, AQSTAT 
The AQIO User's Guide, SN-0247 



SR-0113 



12-23 



D 



ASYNCMS<3IO) 



ASYNCMS(3IO) 



NAME 

ASYNCMS, ASYNCDR - Set I/O mode for random access routines to asynchronous 

SYNOPSIS 

CALL ASYNCMS(rf«[^rr]) 
CALL ASYNCm(dnUerr]) 

DESCRIPTION 

dn The name of the dataset as a Hollerith constant or the unit number of the dataset (for exam- 

ple, dn-1 corresponds to dataset FT07). Hollerith constant dataset names must be from 1 to 
7 uppercase characters. Specify a type integer variable, expression, or constant. 

ierr Error control and code. Specify a type integer variable. If ierr is supplied on the call to 

ASYNCMS/ASYNCDR, ierr returns any error codes to you. If ierr>0> no error messages are 
put into the log file. Otherwise, an error code is returned, and the message is added to the 
job's log file. On output from ASYNCMS/ASYNCDR: 

ierr=Q No errors detected 

<0 Error detected ierr contains one of the error codes 
described in the following table: 



Error Codes 


-1 


The dataset name or unit number is illegal 


-15 


OPENMS/OPENDR was not called on this dataset 



As ASYNCMS/ASYNCDR sets the I/O mode for the random access routines to be asynchronous, I/O 
operations can be initiated, and subsequent execution can proceed simultaneously with the actual data 
transfer. If you use READMS, precede asynchronous reads with calls to FIND MS. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

OPENMS, WRTTMS, READMS, CLOSMS, FINDMS, CHECKMS, WAITMS, SYNCMS, OPENDR, 
WRITDR, READDR, CLOSDR, STTNDR, CHECKDR, WAITDR, SYNCDR, STINDX 
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NAME 

CHECKMS, CHECKDR - Checks status of asynchronous random access I/O operation 

SYNOPSIS 

CALL CHECKMSidnjstatUen]) 
CALL CHECKI>R(dn t istatLierr]) 

DESCRIPTION 

dn The name of the dataset as a Hollerith constant or the unit number of the dataset. (For 

example, dn=7 corresponds to dataset FT07.) Hollerith constant dataset names must be 
from 1 to 7 uppercase characters. Specify a type integer variable, expression, or constant. 

istat Dataset I/O Activity flag. Specify a type integer variable. 

=0 No I/O activity on the specified dataset 
=1 I/O activity on the specified dataset 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

CHECKMS/CHECKDR, ierr returns any error codes to you. If ierr>Q t no error messages 
are put into the log file. Otherwise, an error code is returned, and the message is added to 
the job's log file. On output from CHECKMS^CHEC KDR : 

ierr=Q No error detected 

ierr<0 Error detected, ierr contains one of the error codes 
in the following table: 



ERROR CODES 


-1 


The dataset name or unit number is illegal 


-15 


OPENMS/OPENDR was not called on this dataset. 



A status flag is returned to you, indicating whether the specified dataset is active. 
IMPLEMENTATION 

These routines are available to users of both the COS and UMCOS operating systems. 

SEE ALSO 

OPENMS, WRITMS, READMS, CLOSMS, FINDMS, WAITMS, ASYNCMS, SYNCMS, OPENDR, 
WRITDR, READDR, CLOSDR, STINDR, WAITDR, ASYNCDR, SYNCDR, STINDX 
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NAME 

CHECKTP - Checks tape I/O status 

SYNOPSIS 

CALL CHECKTP (dn,istat,icbuf) 

DESCRIPTION 

dn Type INTEGER variable, expression, or constant. The name of the dataset as a Hollerith 

constant or the unit number of the dataset 

istat Type INTEGER variable 

=-1 No status 

= 0 EOV 

= 1 Tape off reel 

= 2 Tape mark detected 

= 3 Blank tape detected 

icbuf Type INTEGER variable. Circular I/O buffer status. 

= 0 Circular I/O buffer empty 
= 1 Circular I/O buffer not empty 

The user program can use CHECKTP to check on a tape dataset' s condition following normal Fortran 
VO requests. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

CONTPIO, PROCBOV, PROCEOV, SWITCHV, SVOLPRC 
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NAME 

CLOSEV - Begins user EOV and BOV processing 

SYNOPSIS 

CLOSEV(dnltrailer]) 

DESCRIPTION 

A user program uses the CLOSEV subroutine to switch to the next tape volume at any time. CLOSEV 
writes an end-of-volume (EOV) trailer label to a mounted output tape before switching tapes. CLOSEV 
applies only to magnetic tape datasets. 

If the tape is an input tape, you have the option of writing an EOV trailer label An output tape job is 
aborted if the output buffer is not empty. 

In special EOV processing, the user program must execute the CLOSEV subprogram to switch to the 
next tape and perform special beginning-of-volume (BOV) processing. After the CLOSEV macro is exe- 
cuted, the next tape is at the beginning of the volume. The user program is permitted BOV processing 
at this time. After the BOV processing is completed, the user program must execute the ENDSP subpro- 
gram to inform the operating system that special processing is complete and to continue normal pro- 
cessing. 



dn Dataset name or unit number 

trailer A logical constant, variable, or expression. If a value of .TRUE, is specified, a trailer EOV 
label is written. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

CLOSMS, CLOSDR - Writes master index and closes random access dataset 

SYNOPSIS 

CALL CLOSMS(rf*L*err]) 
CALL CLOSDR(dnUerr]) 

DESCRIPTION 

dn The name of the dataset as a Hollerith constant or the unit number of the dataset (For 

example, dn=7 corresponds to dataset FT07.) Hollerith constant dataset names must be 
from 1 to 7 uppercase characters. Specify a type integer variable, expression, or constant. 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

CLOSMS/CLOSDR, ierr returns any error codes to you. If /er/>0, no error messages are 
put into the log file. Otherwise, an error code is returned, and the message is added to the 
job's log file. On output from CLOSMS/CLOSDR: 

ierr^O No error detected 

ierr<0 Error detected, ierr contains one of the error codes 
in the following table: 



ERROR CODES 


-1 


The dataset name or unit number is illegal 


-15 


OPENMS/OPENDR was not called on this dataset. 



CLOSMS/CLOSDR writes the master index specified in OPENMS/OPENDR from the user program area 
to the random access dataset and then closes the dataset. Statistics on the activity of the random access 
dataset and written to dataset $STATS (see table CLOSMS Statistics following). After the random access 
dataset has been closed by CLOSMS/CLOSDR, the statistics can be written to $OUT using the following 
control statements or their equivalent: 

REWIND,DN=$STATS. 
COPYF,I=$STATS,0=$OUT. 

CLOSMS/CLOSDR write a message to $LOG upon closing the dataset, whether or not you have 
requested that error messages be written to the logfile. 

CAUTION 

If a job step terminates without closing the random access dataset with CLOSMS/CLOSDR, dataset 
integrity is questionable* 
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CLOSMS Statistics 


Message 


Description 


TOTAL ACCESSES = 
READS = 
WRITES = 

SEQUENTIAL READS = 
SEQUENTIAL WRITES = 
REWRITES IN PLACE = 
WRITES TO EOI « 
TOTAL WORDS MOVED = 
MINIMUM RECORD = 
MAXIMUM RECORD = 
TOTAL ACCESS TIME - 
AVERAGE ACCESS TIME = 


Number of accesses 
Number of reads 
Number of writes 
Number of sequential reads 
Number of sequential writes 
Number of rewrites in place 
Number of writes to EOI 
Number of words moved 
Minimum record size 
Maximum record size 
Total access time 
Average access time 



IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

CONTPIO - Continues normal I/O operations (obsolete) 

SYNOPSIS 

CALL CONTPIO (dnjprc) 

DESCRIPTION 

dn Type INTEGER variable, expression, or constant The name of the dataset as a Hollerith 

constant or the unit number of the dataset. 

iprc Type INTEGER variable 

=? 2 Continue normal I/O 

=-1 End-of-data (close tape dataset) 

The user program can use CONTPIO to inform COS that it intends to continue normal I/O operations. 
This routine may also be used to close the tape dataset. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

NOTE 

Cray Research discourages the use of the CONTPIO, PROCBOV, PROCEOV, SWITCHV, and SVOL- 
PROC routines. Instead, use CLOSEV, SETSP, STARTSP, and ENDSP when creating special tape pro- 
cessing routines to handle end-of-volume conditions. 

SEE ALSO 

CHECKTP, PROCBOV, PROCEOV, SWITCHV, SVOLPRC 
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NAME 

ENDSP - Requests notification at the end of a tape volume 

SYNOPSIS 

CALL ENDSP(<to) 

DESCRIPTION 

ENDSP indicates to COS that special end-of-volume (EOV) and beginning-of-volumen (BOV) processing 
is complete. 

ENDSP does not switch volumes; when the user program wants to switch to the next tape, it must exe- 
cute CLOSEV. Furthermore, for output datasets, data in the I/O Processor (IOP) buffer is not written to 
tape until ENDSP is executed at the beginning of the next tape. When the BOV processing is done, the 
user program must execute ENDSP to terminate special processing. After executing ENDSP, the user 
program can continue to process the tape dataset, 

dn Dataset name or unit number 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

FTNDMS - Reads record into data buffers used by random access routines 

SYNOPSIS 

CALL FINDMSidn^irecUerr]) 

DESCRIPTION 

dn The name of the dataset as a Hollerith constant or the unit number of the dataset (for exam- 

ple, dn=l corresponds to dataset FT07. Hollerith constant dataset names must be from 1 to 
7 characters. Specify a type integer variable, expression, or constant 

n The number of words to be read, as in READMS or WRITMS. Type integer variable, 

expression, or constant. 

irec As in READMS or WRITMS, the record name or number to be read into the data buffers. 

Specify a type integer variable, expression, or constant 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

FTNDMS, ierr returns any error codes to you. If ierr>0> no error messages are put into the 
log file. Otherwise, an eiror code is returned, and the message is added to the job's log 
file. 

On output from FTNDMS: 
ierr=Q No errors detected 

ierr<Q Error detected, ierr contains one of the error codes 
in following table: 



Error Codes 


-6 


The user-supplied named index is invalid 


-8 


The index number is greater than the maximum 
on the dataset 


•10 


The named record was not found is the index array 


-15 


OPENMS/OPENDR was not called on this dataset 


-17 


The index entry is less than or equal to 0 
in the users index array 


-18 


The user-supplied word count is less than or 
equal to 0 


-19 


The user-supplied index number is less than or 
equal to 0 



FTNDMS asynchronously reads the desired record into the data buffers used by the random access 
dataset routines for the specified dataset The next READMS or WRITMS call waits for the read to 
complete and transfers data appropriately. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

OPENMS, WRITMS, READMS, CLOSMS, CHECKMS, WAITMS, ASYNCMS, SYNCMS, OPENDR, 
WRITDR, READDR, CLOSDR, STINDR, CHECKDR, WAITDR, ASYNCDR, SYNCDR, STBMDX 
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NAME 

FSUP, ISUP - Output a value in an argument as blank in Fortran format 

FSUPC, ISUPC - Invalidate the function obtained by calling FSUP or ISUP, returning to ordinary I/O 

SYNOPSIS 

CALL FSUPtfvalue) 
CALL ISUP(iWj«?) 
CALL FSUPC 

CALL ISUPC 
DESCRIPTION 

fvalue and ivalue are real and integer arguments, respectively. If FSUP is not called, F-type, G-type, and 
E-type values are output as for ordinary Fortran I/O. When FSUP is called, all values equal to fvalue 
are output as blanks whenever they are encountered in a formatted I/O operation. FSUP may be called 
again to redefine itself. 

FSUPC invalidates the call from FSUP, and all types are output as ordinary Fortran I/O. 

ISUP and ISUPC are the integer equivalents of FSUP and FSUPC. ISUP acts upon I-type, O-type, and 
Z-type values. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

GETPOS, SETPOS - Returns the current position of interchange tape or mass storage dataset or file; 
returns to position retained from GETPOS request. 

SYNOPSIS 

CALL GETPQ$(dnJen,pa[ t stat]) 

CALL SETVOS(dn t len,pa[>st<ti]) 
DESCRIPTION 

GETPOS returns the current position of the specified interchange tape or mass storage dataset to the 
Fortran user. GETPOS does not alter the dataset' s position, but it captures information that you can use 
later to recover the current position. 

SETPOS lets you return to the position retained from the GETPOS request. SETPOS, like GETPOS, can 
be used on interchange tape or mass storage datasets. 

dn Dataset name, file name, or unit number 

len Length in Cray words of the position airay. This parameter determines the maximum 

number of position values to return or process. For SETPOS, this parameter allows for the 
addition of more information fields while ensuring that existing codes continue to run. Pos- 
sible values for len are: 

1 For disk datasets 

2 For tape datasets 

3 For disk or tape datasets recorded as a foreign dataset 

pa Position array. On exit, pa contains the current position information. For GETPOS, you 

should not modify this information. It should be retained to be passed on to SETPOS. For 
SETPOS, pa contains the desired position information from the GETPOS call. The format 
of the position information is as follows: 

• For a disk dataset, one word that contains the current position. 

• For a tape dataset, two words; word 0 contains the volume serial number of the 
current tape reel, and word 1 contains the block number before which the tape unit is 
positioned. 

• For a foreign tape dataset, three words; word 0 contains the block number before 
which the tape unit is positioned, word 1 contains the volume serial number of the 
current tape reel, and word 2 contains the block length. 

stat Return conditions. This optional parameter returns errors and warnings from the position 

information routine, as follows: 

=0 For GETPOS, indicates position information successfully returned. For SETPOS, 
indicates dataset successfully positioned. 

*0 Error or warning encountered during request Error message number; see coded 
SIOLIB messages in the COS Message Manual, publication SR-0039. 
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To set the position of a mass storage dataset, the position must be at a record boundary; that is, at die 
beginning-of-dataset (BOD), following an end-of-record (EOR) or end-of-file (EOF), or before an end- 
of-dataset (EOD), A dataset cannot be positioned beyond the current EOD. 

SETPOS positions to a logical record when processing a foreign file with the library data conversion 
support (FD parameter on the ACCESS and ASSIGN control statements). This same capability also 
exists for mass storage files that have been assigned foreign dataset characteristics. 

If foreign dataset conversion has not been requested, the physical tape block and volume position is 
determined. 



For interchange tape dataset, SETPOS must synchronize before the dataset can be positioned. Thus, for 
input datasets, the dataset must be positioned at a Cray EOR. An EOR is added to the EOD before the 
synchronization if the dataset is an output dataset and the end of the tape block was not already written. 

NOTE 

For disk files only, GETPOS and SETPOS also support calls of the following form; 

pv = GETPOS^ 
CALL SETPOS(rfn,pv) 

where dn is the dataset or file name or number, and pv is the position value. 



IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. UNICOS does not 
support the positioning of blocked files or tapes or of foreign files (those in non-Cray format). 



SEE ALSO 

GETTP, SETTP, SYNCH 
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NAME 

GETTP - Receives position information about an opened tape dataset or file 

SYNOPSIS 

CALL GETTP(dnJen t pa t synch,istat) 

DESCRIPTION 

dn Name of the dataset, file, or unit number to get the position information. Must be an 

integer variable, or an array element containing Hollerith data of not more than 7 charac- 
ters. This parameter should be of the form 'dn'L. 

ten Length in Cray words of the position array pa. GETTP uses this parameter to determine the 

maximum number of position values to return. This parameter allows for the addition of 
more information fields while ensuring that existing codes continue to run. Currently, 15 
words are used, 

pa Position array. On exit, pa contains the current position information, as follows: 

pa(l) Volume Identifier of last block processed 
pa(2) Characters 1 through 8 of permanent dataset name or file name 
pa(3) Characters 9 through 16 of permanent dataset name or file name 
pa(A) Characters 17 through 24 of permanent dataset name or file name 
pa(5) Characters 25 through 32 of permanent dataset name or file name 
pa{6) Characters 33 through 40 of permanent dataset name or file name 
pa(J) Characters 41 through 44 of permanent dataset name or file name 
pa(S) File section number 
pa(9) File sequence number 
pa(l0) Block number 

pa(\l) Number of blocks in the circular buffer. On output, blocks not sent to I/O 
Processor (IOP); on input, always 0. 

pa(12) Number of blocks in the IOP buffer 

paQ3) Device ID (unit number) 

pa(\4) Device identifier (name) 

pa(\S) Generic device name 

synch Synchronize tape dataset or file. GETTP uses this parameter to determine whether to syn- 
chronize the program and an opened tape dataset or file before obtaining position informa- 
tion. Synchronization, if requested, is done according to the current positioning direction. 

=0 Do not synchronize tape dataset or file 

-1 Synchronize tape dataset or file before obtaining position information 
istat Return conditions. This parameter returns errors and warnings from the position routine. 
=0 Dataset or file position information successfully returned 
*0 Error or warning encountered during request 
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The GETTP routine lets you receive information about an opened tape dataset or file. The information 
returned by GETTP refers to the last block processed if the dataset is an input dataset. For output 
datasets, the information returned by GETTP can be meaningless unless the tape dataset or file has been 
synchronized. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

SETTP, GETPOS, SYNCH 
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NAME 

GETWA, SEEK - Synchronously and asynchronously reads data from the word-addressable, random 
access dataset 

SYNOPSIS 

CALL GKTViK{dn t resultAddr t countUerr\) 
CALL SEEK(dn t addr t countUerr\) 

DESCRIPTION 

dn The name of the dataset as a Hollerith constant or the unit number of the dataset (for exam- 

ple, div=H corresponds to FT07). Hollerith constant dataset names must be from 1 to 7 char- 
acters. Specify a type integer variable, expression, or constant. 

result Variable or array of any type. The location in the user program where the first word is 
placed. 

addr For GETWA, the word location of the dataset from which the first word is transferred. For 
SEEK, the word address of the next read. Specify a type integer variable, expression, or 
constant 

count For GETWA, the number of words from result written from the dataset into user memory. 

For SEEK, the number of words of the next read. Specify a type integer variable, expres- 
sion, or constant. 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

GETWA or SEEK, ierr returns any error codes to you. If ierr is not supplied, an error 
aborts the job. 

On output from GETWA: 
/ern=0 No errors detected 

<0 Error detected, ierr contains one of the error codes in 
the following table: 



Error Codes 


-1 


Illegal unit number 


-2 


The number of datasets has exceeded memory 
or size availability 


-3 


User attempt to read past end-of-data (EOD) 


-4 


The user-supplied word address less than or 
equal to 0 


-5 


User-requested word count greater than maximum 
allowed 


-6 


Illegal dataset name 


-7 


User word count less than or equal to 0 



The SEEK and GETWA calls are used together. The SEEK call reads the data asynchronously; the 
GETWA call waits for I/O to complete and then transfers the data. The SEEK call moves the last write 
operation pages from memory to disk, loading the user-requested word addresses to the front of the I/O 
buffers. You can load as much data as fits into the dataset buffers. Subsequent GETWA and PUTWA 
calls that reference word addresses in the same range do not cause any disk I/O. 
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IMPLEMENTATION 

These routines are available to users of both the COS and UMCOS operating systems, 

NOTE 

Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are 
single threaded. Some library routines, however, must be locked at the user level if they are used by 
more than one task. 

GETWA is not internally locked. You must lock each call to GETWA if it is called from more than one 
task. 



EXAMPLE 

Assume you want to use a routine that reads word addresses 1,000,000 to 1,051,200. A dataset is 
opened with 101 blocks of buffer space, and CALL SEEK(^1000000 9 51200 9 ierr) is used before cal- 
ling the routine. Subsequent GETWA or PUTWA calls with word addresses in the range of 1,000,000 to 
1,051,200 do not trigger any disk I/O. 



SEE ALSO 

WOPEN, WCLOSE, PUTWA, APUTWA 
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NAME 

GETWAU - Asynchronously reads a number of words from the disk, direcfly to user 
SYNOPSIS 

CALL GK^AV(dn t resutt t addr t countUerr]) 
DESCRIPTION 

dn Name of the dataset as a Hollerith constant, or the unit number of the dataset (for example, 

dn-1 corresponds to FT07). Hollerith constant dataset names must be from 1 to 7 charac- 
ters. Specify a type integer variable, expression, or constant. 

result Variable or array of any type. The location in the user program at which the first word is 
placed. 

addr The word location of the dataset from which the first word is read Starts with 1, not 0. 

The word location must specify a sector boundary. That is, it must be of the form 
(n*512)+l forn=0,l,2„... 

count The number of words to read from disk. Must be a multiple of 512. 

ierr Error control and code. Specify a type integer variable. If ierr is not supplied, an error 

aborts the job. 

On output from GETWAU: 
ierr=0 No errors detected 

<0 Error detected, ierr contains one of the error codes in 
the following table: 



Error Codes 


-1 


Illegal unit number 


-2 


The number of files has exceeded memory 
or size availability 


-3 


User attempt to read past end-of-data (EOD) 


-4 


The user-supplied word address less than or 
equal to 0 


-5 


User-requested word count greater than maximum 
allowed 


-6 


Illegal dataset name 


•7 


User word count less than or equal to 0 
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NOTES 

Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are 
single threaded. Some library routines, however, must be locked at the user level if they are used by 
more than one task. 

GETWAU is not internally locked. You must lock each call to GETWAU if it is called from more than 
one task. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

WINITU, WRITEWA, READ WA 
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NAME 

OPENMS, OPENDR - Opens a local dataset as a random access dataset that can be accessed or changed 
by the record-addressable, random access dataset I/O routines 

SYNOPSIS 

CALL OPENMSidnMdexJengthMJerr]) 
CALL OPENDR(dn t indexJength t it[4err]) 



DESCRIPTION 



dn The name of the dataset as a Hollerith constant or the unit number of the dataset (for exam- 

ple, dn-1 corresponds to dataset FT07), Hollerith constant dataset names must be from I to 
7 characters. Specify a type integer variable, expression, or constant. 

index The name of the array in the user program that is going to contain the master index to the 
records of the dataset Specify a type integer array. This array must be changed only by 
the random access dataset I/O routines, index should be a multiple of 512 words. 

length The length of the index array. Specify a type integer variable, expression, or constant. The 
length of index depends upon the number of records on or to be written to the dataset using 
the master index and upon the type of master index. The length specification must be at 
least 2*nrec if it=l or 3, or nrec if it=Q or 2. nrec is the number of records in or to be 
written to the dataset using the master index. 

it Flag indicating the type of master index. Specify a type integer variable, expression, or 

constant. 

ifcO Records synchronously referenced with a number between 1 and length 

it=l Records synchronously referenced with an alphanumeric name of 8 or fewer char- 
acters 

/f=2 Records asynchronously referenced with a number between 1 and length 

it=3 Records asynchronously referenced with an alphanumeric name of 8 or fewer 
characters 



For a named index, odd-numbered elements of the index array contain the record name, and 
even-numbered elements of the index array contain the pointers to the location of the record 
within the dataset. For a numbered index, a given index array element contains the pointers 
to the location of the corresponding record within the dataset. 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

OPENMS/OPENDR, ierr returns any error codes to you. If ierr is not supplied, an error 
aborts the job. 

If you set ierr>0 on input to OPENMS/OPENDR, error messages are not placed in the 
logfile. Otherwise, an error code is returned, and the error message is added to the job's 
logfile. OPENMS/OPENDR writes an open message to the logfile whether or not the value 
of ierr selects log messages. 
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On output from OPENMS/OPENDR: 
ierr=0 No errors detected 

<0 Error detected ierr contains one of the following error codes: 



Error Codes 


-1 


The dataset name or unit number is illegal 


-2 


The user-supplied index length is less than 
or equal to 0 


-3 


The number of datasets has exceeded memory 
or size availability 


-4 


The dataset index length read from the dataset 
is greater than the user-supplied index length 
(nonfatal message) 


-5 


The user-supplied index length is greater than 
the index length read from the dataset 
(nonfatal message) 


-11 


The index word address read from the dataset is less 
than or equal to 0 


-12 


The index length read from the dataset is less than 0 


-13 


The dataset has a checksum error 


-14 


OPENMS has already opened the dataset 


-20 


Dataset created by WRITDR/WRITMS 



IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTES 

A file opened with OPENMS should only be closed by CLOSMS. If you close the file in some other 
way, the future behavior of the program is unpredictable. 

SEE ALSO 

WRITMS, READMS, CLOSMS, FINDMS, CHECKMS, WAITMS, ASYNCMS, SYNCMS, WRITDR, 
READDR, CLOSDR, STINDR, CHECKDR, WAITDR, ASYNCDR, SYNCDR, STONDX 
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NAME 

PROCBOV - Allows special processing at beginning-of-volume (BOV) (obsolete) 

SYNOPSIS 

CALL mOCBQ\(dn,iprc) 

DESCRIPTION 

dn Type INTEGER variable, expression, or constant. The name of the dataset as a Hollerith 

constant or unit number of the dataset. 

iprc Type INTEGER variable 

= 1 Special processing at BOV 

= 2 Continue normal I/O 

=-1 End-of-data (close tape dataset) 

The user program can use PROCBOV to inform COS that it intends to reposition or perform special I/O 
processing to the tape. This routine assumes that the tape dataset is positioned at BOV. PROCBOV 
allows special processing at beginning-of-volume. This routine may also be used to continue normal 
I/O or close the tape dataset. 

NOTE 

Cray Research discourages the use of the CONTPIO, PROCBOV, PROCEOV, SWITCHV, and SVOL- 
PROC routines. Instead, use CLOSEV, SETSP, STARTSP, and ENDSP when creating special tape pro- 
cessing routines to handle end-of-volume conditions. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

CHECKTP, CONTPIO, PROCEOV, SWITCHV, SVOLPRC 
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NAME 

PROCEOV - Begins special processing at end-of-volume (EOV) (obsolete) 

SYNOPSIS 

CALL PROCEOV(dn t iprc) 



DESCRIPTION 



dn Type INTEGER variable, expression, or constant. The name of the dataset as a Hollerith 

constant or unit number of the dataset. 

iprc Type INTEGER variable. 

- 0 Special processing at EOV 
= 1 Special processing at BOV 
= 2 Continue normal I/O 
=^1 End-of-data (close tape dataset) 



The user program can use PROCEOV to inform COS that it intends to reposition or perform special I/O 
processing to the tape. This routine assumes that the tape dataset is positioned at EOV. PROCEOV 
allows special processing at BOV EOV. This routine may also be used to continue normal I/O or to 
close the tape dataset. 

NOTE 

Cray Research discourages the use of the CONTPIO, PROCBOV, SWITCHV, PROCEOV, and SVOL- 
PROC routines. Instead, use CLOSEV, SETSP, STARTSP, and ENDSP when creating special tape pro- 
cessing routines to handle end-of-volume conditions. 



IMPLEMENTATION 

This routine is available only to users of the COS operating system. 



SEE ALSO 

CHECKTP, CONTPIO, PROCBOV, SWITCHV, SVOLPRC 
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NAME 

PUTWA, APUTWA - Writes to a word-addressable, random-access dataset 
SYNOPSIS 

CALL PVTWA(dn 1 source f addr t countUerr]) 
CALL APUTWA(dn,source,addr t counttierr]) 

DESCRIPTION 

dn Name of the dataset as a Hollerith constant or the unit number of the dataset Specify a 

type integer variable, expression, or constant. 

source Variable or array of any type. The location of the first word in the user program to be 
written to the dataset 

addr The word location of the dataset that is to receive the first word from the user program. 

addr=l indicates beginning of file. Specify a type integer variable, expression, or constant 

count The number of words from source to be written. Specify a type integer variable, expres- 
sion, or constant 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

PUTWA, ierr returns any error codes to you. If ierr is not supplied, an error causes the job 
to abort. 

On output from PUTWA/APUTWA: 

iern=Q No errors detected 
•1 Invalid unit number 

-2 Number of datasets has exceeded memory size availability 

-4 User-supplied word address less than or equal to 0 

-5 User-requested word count greater than maximum allowed 

-6 Invalid dataset name 

-7 User word count less than or equal to 0 
PUTWA synchronously writes a number of words from memory to a word-addressable, random-access 
dataset. APUTWA asynchronously writes a number of words from memory to a word-addressable, 
random-access dataset 

NOTE 

Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are 
single threaded. Some library routines, however, must be locked at the user level if they are used by 
more than one task. 

PUTWA is not internally locked. You must lock each call to PUTWA if it is called from more than one 
task. 

IMPLEMENTATION 

These routines are available to users of both the COS and UMCOS operating systems. 

SEE ALSO 

WOPEN, WCLOSE, GETWA, SEEK 
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NAME 

PUTWAU - Writes to a word-addressable, random-access dataset, unbuffered 
SYNOPSIS 

CALL ¥\yrWAV(dn t source f addr t countUierr]) 
DESCRIPTION 

dn Name of the dataset as a Hollerith constant, or the unit number of the dataset Specify a 

type integer variable, expression, or constant. 

source Variable or array of any type. The location of the first word in the user program to be 
written to the dataset 

addr The word location of the dataset that is to receive the first word from the user program. 

addr^l indicates beginning of file. Specify a type integer variable, expression, or constant. 
The word location must specify a sector boundary. That is, it must be of the form 
(n*512)+l for n=0,l,2,.„. 

count The number of words from source to be written. Must be a multiple of 512. Specify a type 
integer variable, expression, or constant. 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

PUTWAU, ierr returns any error codes to you. If ierr is not supplied, an error aborts the 
job. 

On output from PUTWAU: 
ierr=0 No errors detected 

<0 Error detected, ierr contains one of the error codes in 
the following table: 



Error Codes 




Invalid unit number 


-2 


The number of datasets has exceeded memory 
or size availability 


-4 


The user-supplied word address less than or 
equal to 0 


-5 


User-requested word count greater than maximum 
allowed 


-6 


Invalid dataset name 


-7 


User word count less than or equal to 0 



PUTWAU asynchronously writes a number of words from memory to a word-addressable, random- 
access dataset. 
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NOTES 

Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are 
single threaded. Some library routines, however, must be locked at the user level if they are used by 
more than one task. 

PUTWAU is not internally locked. You must lock each call to PUTWAU if it is called from more than 
one task. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

WOPEN, WCLOSE, GETWA, SEEK 
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NAME 

READ, READP - Reads words, full or partial record modes 

SYNOPSIS 

CALL READ(dn,word,countftatus,ubc) 
CALL READP(dn,word,count,siatus,ubc) 

DESCRIPTION 

dn Unit number or file name as a Hollerith in seven characters or less ('MYFILE') 

word Word-receiving data area, such as a variable or array 

count On entry, the number of words requested. (Do not specify a constant) On exit, the number 
of words actually transferred. 

status On exit, status has one of the following values: 
=-1 Words remain in record 
= 0 EOR 
= 1 Null record 
= 2 End-of-file (EOF) 
= 3 End-of-data (EOD) 
= 4 Hardware error 

ubc Optional unused bit count Number of unused bits contained in the last word of the record. 

READ and READP move words of data from disk to a user's variable or array. They are intended to 
read COS blocked datasets. After reading less than a full record from disk, READ leaves the file posi- 
tioned at the beginning of the next record, while READP leaves the file positioned at the next item in 
the record just read. 

EXAMPLE 

The following example reads the first two words of two consecutive records: 

INTEGER REC(IO) 
NUM = 2 

CALL READ(DN= 1 5 , REC, NUM) 
NUM = 2 

CALL READ ( DN= 1 5 , REC, NUM) 
STOP 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

READC, READCP, READIBM, WRITE, WRITEP, WRITEC, WRITECP, WRITIBM, SKIPBAD, 
ACPTBAD 
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NAME 

READC, READCP - Reads characters, full or partial record mode 

SYNOPSIS 

CALL READC(dn,char,count .status) 
CALL KEADCPidritChancourajtatus) 

DESCRIPTION 

dn Unit number 

char Character-receiving data area 

count On entry, the number of characters requested. On exit, the number of characters actually 
transferred. 

status On exit, status has one of the following values: 
=-1 Characters remain in record 
= 0 End-of-record (EOR) 
= 1 Null record 
= 2 End-of-file (EOF) 

Read character routines unpack characters from the I/O buffer and insert them into the user data area 
beginning at the first word address. Characters are placed into the data area one character per word, 
right-justified. This process continues until the count is satisfied or an EOR is encountered. If an EOR 
is encountered first, the remainder of the field specified by the character count is filled with blanks. 
Blank expansion is performed on the characters read from the buffer to die data area. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

READ, READP, READIBM, WRITE, WRITEP, WRITEC, WRITECP, WRITTBM, SKIPBAD, ACPTBAD 
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NAME 

READIBM - Reads two IBM 32-bit floating-point words from each Cray 64-bit word 
SYNOPSIS 

CALL READIBM(dnjwa,word t increment) 

DESCRIPTION 

dn Dataset name or unit number 

fwa First word address (FWA) of the user data area 

word Number of words needed 

increment Increment of the EM words read 

On exit, the IBM 32-bit format is converted to the equivalent Cray 64-bit value. The Cray 64-bit words 
are stored in the user data area. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNECOS operating systems. 

SEE ALSO 

READ, READP, READC, READCP, WRITE, WRITEP, WRITEC, WRITECP, WRITIBM, SKIPBAD, 
ACPTBAD 
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NAME 

READMS, READDR - Reads a record from a random access dataset 

SYNOPSIS 

CALL RE ADM S (dh ,ubuff t n,irec [4err]) 
CALL READDR(dn,ubuff t n,irecUerr]) 

DESCRIPTION 

READMS and READDR read records from a random access dataset to a contiguous memory area in the 
user's program. 



dn The name of the dataset as a Hollerith constant or the unit number of the dataset. Hollerith 

constant dataset names must be from 1 to 7 characters. Specify a type integer variable, 
expression, or constant. 

ubuff The location in your program where the first word of the record is placed. User-specified 
type. 

n The number of words to be read. Specify a type integer variable, expression, or constant. 

n words are read from the random access record irec and placed contiguously in memory, 
beginning at ubuff. If necessary, READDR rounds n up to the next multiple of 512 words. 
If the file is in synchronous mode, the data is saved and restored after the read. 

irec The record number or record name of the record to be read. Specify a type integer variable, 

expression, or constant A record name is limited to a maximum of 8 characters. For a 
numbered index, irec must be between 1 and the length of the index declared in the 
OPENMS/OPENDR call, inclusive. For a named index, irec is any 64-bit entity you specify. 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

READMS/READDR, ierr returns any error codes to you, If *err>0, no error messages are 
put into the logfile. Otherwise, an error code is returned, and the message is added to the 
job's logfile. 



On output from READMS/READDR: 
ierr=0 No errors detected 

<0 Error detected, ierr contains one of the error codes 
in the following table: 
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Error Codes 


-1 


The dataset name or unit number is invalid 


-6 


pfrai 1*1 1*1 VI 1*4 

The user-supplied named index is invalid 


-7 


The named record index array is full 


-8 


The index number is greater than the maximum 
on the dataset 


-9 


Rewrite record exceeds the original 


-10 


The named record was not found is the index array 


-15 


OPENMS/OPENDR was not called on this dataset 


-17 


The index entry is less than or equal to 0 
in the users index array 


-18 


The user-supplied word count is less than or 
equal to 0 


-19 


The user-supplied index number is less than or 
equal to 0 



WARNING 

If you are using READDR in asynchronous mode, and the record size is not a multiple of 512 words, 
user data can be overwritten and not restored. With SYNCDR, the dalasel can be switched to read syn- 
chronously, causing data to be copied out and restored after the read has completed. 

NOTE 

Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are 
single threaded. Some library routines, however, must be locked at the user level if they are used by 
more than one task. 

READMS and READDR are not internally locked. You must lock each call to these routines if they are 
called from more than one task. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

OPENMS, WRITMS, CLOSMS, FINDMS, CHECKMS, WAITMS, ASYNCMS, SYNCMS, OPENDR, 
WRITDR, CLOSDR, STINDR, CHECKDR, WAITDR, ASYNCDR, SYNCDR, STINDX 
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NAME 

RNLFLAG, RNLDELM, RNLSEP, RNLREP, RNLCOMM - Adds or deletes characters from the set of 
characters recognized by the NAMELIST input routine 

SYNOPSIS 

CALL KNLFLAGichanrnode) 
CALL RNLDELM(c/uzr,m0de) 
CALL KNLSEP(charjnode) 
CALL RNLKEP(char t mode) 
CALL RNLCOMM(char t mode) 

DESCRIPTION 

char For RNLFLAG, an echo character. Default is *E\ 

For RNLDELM, a delimiting character. Default is T and *&*. 

For RNLSEP, a separator character. Default is V . 

For RNLREP, a replacement character. Default is *=\ 

For RNLCOMM, a trailing comment indicator Defaults are Y and *;\ 

mode =0 Delete character 
*0 Add character 

In each of these user-control subroutine argument lists, char is a character specified as lLx or lRx. 

RNLFLAG adds or removes char from the set of characters that, if found in column 1, initiates echoing 
of the input lines to $OUT. 

RNLDELM adds or removes char from the set of characters that precede the NAMELIST group name 
and signal end-of-input. 

RNLSEP adds or removes char from the set of characters that must follow each constant to act as a 
separator. 

RNLREP adds or removes char from the set of characters that occur between the variable name and 
the value. 

RNLCOMM adds or removes char from the set of characters that initiate trailing comments on a line. 
No checks are make to determine the reasonableness, usefulness, or consistency of these changes, 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

RNLSKIP, RNLECHO, RNLTYPE, WNL, WNLLONG, WNLLINE 
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NAME 

RNLECHO - Specifies output unit for NAMELIST error messages and echo lines 

SYNOPSIS 

CALL RNLECHO(uflir) 

DESCRIPTION 

unit Output unit to which error messages and echo lines are sent If unit=Q, error messages and 

lines echoed because of an E in column 1 go to SOUT (default). 

If unit *0, error messages and input lines are echoed to unit, regardless of any echo flags 
present. If unti=6 or itro<= 101, SOUT is implied. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

RNL, RNLSKIP, RNLTYPE WNL, WNLLONG, WNLLTNE 
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NAME 

RNLSKIP - Takes appropriate action when an undesired NAMELIST group is encountered 

SYNOPSIS 

CALL RNLSKIP(mode) 

DESCRIPTION 

mode <0 Skips the record and issues a logfile message (default) 
=0 Skips the record 

>0 Aborts the job or goes to the optional ERR= branch 
RNLSKIP determines action if the NAMELIST group encountered is not the desired group. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

RNL, RNLSKIP, RNLECHO WNL, WNLLONG, WNLLINE 
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NAME 

RNLTYPE - Determines action if a type mismatch occurs across the equal sign on an input record 

SYNOPSIS 

CALL RNLTYPE(mode) 

DESCRIPTION 

mode *0 Converts the constant to the type of the variable (default) 
=0 Aborts the job or goes to the optional ERR= branch 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

RNL, RNLSKTP, RNLECHO WNL, WNLLONG, WNLLINE 
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NAME 

SETSP - Requests notification at the end of a tape volume 



SYNOPSIS 

CALL SETS¥(dn t on) 

DESCRIPTION 

SETSP informs the operating system that you wish to perform extra processing when the end of a tape 
volume is reached. You must call SYNCH to ensure all data is written to tape before calling SETSP. 

After the user program has called SETSP, the end-of volume (EOV) condition is set when the tape is 
positioned after the last data block* For an input dataset, this occurs after the system has read the last 
data block on the volume. For an output dataset, this occurs when end-of-tape (EOT) status is detected. 

Automatic volume switching is not done by COS following the successful execution of SETSP with the 
on parameter non-zero. If you want to switch volumes, call CLOSEV. 



dn Dataset name or unit number 

on Type LOGICAL variable, expression, or constant. A value of .FALSE, turns off special 

processing. A value of .TRUE, turns on special processing. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

STARTSP, ENDSP, CLOSEV 
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NAME 

SETTP - Positions a tape dataset or file at a tape block of the dataset or file 
SYNOPSIS 

CALL SETTP(dn,nbs t nb l nvs,nv,vi t $ynch4stat) 
DESCRIPTION 

dn Name of the dataset or file or unit number to be positioned. Must be an integer variable, or 

an array element containing Hollerith data of not more than 7 characters. This parameter 
should be of the form WL. 

nbs Block number request sign. This parameter must be set to either '+'L, '-'L, or ' 'L. See 

the block number parameter (nb) for usage detail. 

nb Block number or number of blocks to forward space or backspace from the current position. 

The direction of the positioning is specified by the block number request sign parameter 
nbs. 

+nb Specifies the number of blocks to forward space from the current position. The nbs 
parameter should be set to *+'L when forward block positioning is desired. The + 
sign is invalid if either nv or vi is requested. 

-nb Specifies the number of blocks to backspace from the current position. The nbs 
parameter should be set to '-'L when backward block positioning is desired. The - 
sign is invalid if either nv or vi is requested. 

nb Specifies the absolute block number to be positioned to. The nbs parameter should 
be set to a blank (* 'L) when absolute block positioning is desired. 

nvs Volume number request sign. This parameter must be set to '+'L, '-'L, or * 'L. See the 

volume number parameter (nv) for usage details. 

nv Volume number or number of volumes to forward space or backspace from the curcent 

position. This parameter should be set equal to a binary volume number or number of 
volumes to forward space or backspace. This direction of the positioning is specified by 
the volume number request sign parameter nvs. This parameter is invalid if vi is also 
requested. 

+nv Specifies the number of volumes to forward space from the current volume. The 
nvs parameter should be set to VL when forward volume positioning is desired. 
An nb request must not be specified with + or - signs. 

-nv Specifies the number of volumes to backspace from the current volume. The nvs 
parameter should be set to *-'L when forward volume positioning is desired. A nb 
request must not be specified with + or - signs. 

nv Specifies the absolute volume number to be positioned to. The nvs parameter 
should be set to ' 'L when absolute volume positioning is desired. 

vi Volume identifier to be mounted. This parameter is invalid if nv is also requested. Also, 

nb must not be specified without + or - signs. The volume identifier must be left-justified, 
zero-filled. 
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synch 



Synchronize tape dataset. SETTP uses this parameter to determine whether to synchronize 
the program and an opened tape dataset before positioning. Synchronization, if requested, 
is done according to the current positioning direction. 



=0 Do not synchronize tape dataset or file 



=1 Synchronize tape dataset or file before positioning 



istat 



Return conditions. This parameter is used to return errors and warnings from the position 
routine. 

-0 Dataset or file successfully positioned 

*0 Error or warning encountered during request 



SETTP allows you to position a tape dataset at a particular tape block of the dataset. Data blocks on 
the tape are numbered so that block number 1 is the first data block on a tape. Before a tape dataset is 
positioned with SETTP, the dataset must be synchronized with the SYNCH routine or with the synchron- 
ization parameter on the SETTP request. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

GETTP, SYNCH, GETPOS 
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NAME 

SKIPBAD - Skips bad data 

SYNOPSIS 

CALL SKlPBAD(dn,blocks,termcnd) 

DESCRIPTION 

dn Dataset name or unit number 

blocks On exit, contains the number of blocks skipped. 

termcnd On exit, termination condition. 

<0 Not positioned at end-of-block 
=0 Positioned at end-of-block 
=1 If 1, positioned at end-of-file 

SKIPBAD allows you to skip bad data so that no bad data is sent to the user-specified buffer. 
EXAMPLE 

PROGRAM EXAMPLE 2 
IMPLICIT INTEGER ( A - Z) 
REAL UNIT. UNIT STAT 

PARAMETER (NBYTES=400000 ,NDIM=NBYTES / 8 ,DN=99 ) 
DIMENSION BUFFER( 1 :NDIM) 
2 00 0 CONTINUE 

NWORDS = NDIM 

CALL READ ( DN , BUFFER , NWORDS , STATUS) 
UN ITS TAT = UNIT(DN) 

IF(STATUS .EQ.4 .OR. UNI TSTAT . GT . 0 . 0 ) THEN 'Parity error 
CALL SKI PBAD(DN. BLOCKS .TERCND) 
I F (TERMCND. LT. 0) THEN 

CALL ABORT ( "SKIPBAD should position tape at EOR/EOf 
END IF 
STOP 'COMPLETE* 
END 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

ACPTBAD 
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NAME 

STARTSP - Begins user EOV and BOV processing 

SYNOPSIS 

CALL STARTSP(<*0 

DESCRIPTION 

STARTSP starts special end-of-volume (EOV) and beginning-of-volume processing. No special- 
processing I/O to the tape occurs until this routine (or the implementing macro) has been executed. 
The user program must inform COS that it intends to reposition or perform special I/O to the tape by 
executing the STARTSP routine. 

After executing the STARTSP routine, the user program can issue READ, WRITE, and SETTP requests. 
When processing is done, the user program must execute ENDSP to inform COS that special processing 
is complete. STARTSP does not switch volumes; when the user program wants to switch to the next 
tape, you must invoke CLOSEV. Moreover, after you execute STARTSP and before you execute 
ENDSP, the CLOSEV call is the only method to perform volume switching for the user program. 

Call SYNCH before executing STARTSP. For output datasets, the data in the IOP buffer is not written 
to tape until the ENDSP call at the beginning of the next tape. 



dn Dataset name or unit number 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

STINDX, STINDR - Allows an index to be used as the current index by creating a subindex 

SYNOPSIS 

CALL STINT)X(dn>index t tengthMlierr]) 
CALL STJNDR(dnjndexJength,itUerr]) 

DESCRIPTION 

dn The name of the dataset as a Hollerith constant or the unit number of the file. Hollerith 

constant dataset names must be from 1 to 7 characters. Specify a type integer variable, 
expression, or constant 

index The user-supplied array used for the subindex or new current index. Specify a type integer 
array. If index is a subindex, it must be a storage area that does not overlap the area used 
in OPENMS/OPENDR to store the master index. 

length The length of the index array. Specify a type integer variable, expression, or constant. The 
length of index depends upon the number of records on or to be written to the dataset using 
the master index and upon the type of master index. If ir=l, length must be at least twice 
the number of records on or to be written to the dataset using index. If it=0> length must be 
at least the number of records on or to be written to the dataset using index. 

it A flag to indicate the type of index. Specify a type integer variable, expression, or con- 

stant. When it=0, the records are referenced with a number between 1 and length. When 
it=l t the records are referenced with an alphanumeric name of 8 or fewer characters. For a 
named index, odd-numbered elements of the index array contain the record name, and 
even-numbered elements of the index array contain pointers to the location of the record 
within the dataset. For a numbered index, a given index array element contains pointers to 
the location of the corresponding record within the dataset The index type defined by 
STINDX/STINDR must be the same as that used by OPENMS/OPENDR. 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

STINDX/STINDR, ierr returns any error codes to you. If ierr>0 9 no error messages are put 
into the log file. Otherwise, an error code is returned, and die message is added to the 
job's log file. 

On output from STINDX/STINDR: 

iern=Q No errors detected 

<0 Error detected, ierr contains one of the error codes described 
in the following table: 



Error Codes 


-I 


The dataset name or unit number is invalid 


-15 


OPENMS/OPENDR was not called on this dataset 


-16 


A STINDX/STINDR 
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STTNDX/STINDR reduce the amount of memory needed by a dataset containing a large number of 
records. It also maintains a dataset containing records logically related to each other. Records in the 
dataset, rather than records in the master index area, hold secondary pointers to records in the dataset. 

STINDX/STINDR allow more than one index to manipulate the dataset. Generally, STINDX/STINDR tog- 
gle the index between the master index (maintained by OPENMS/OPENDR and CLOSMS/CLOSDR) and 
a subindex (supplied and maintained by you). 

You must maintain and update subindex records stored in the dataset Records in the dataset can be 
accessed and changed only by using the current index. 

After a STINDX/STINDR call, subsequent calls to READMS/READDR and WRITMS/WRITDR use and 
alto the current index array specified in the STINDX/STINDR call You can save the subindex by cal- 
ling STINDX/STINDR with the master index array, then writing the subindex array to the dataset using 
WRITMS/WRITDR. Retrieve die subindex by calling READMS/READDR on the record containing the 
subindex information. Thus, STINDX/STINDR allow logically infinite index trees into the dataset and 
reduces the amount of memory needed for a random access dataset containing many records. 

CAUTION 

When generating a new subindex (for example, building a database), set the array or memory area used 
for the subindex to 0. If the subindex storage is not set to 0, unpredictable results occur. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

OPENMS, WRITMS, READMS, CLOSMS, F1NDMS, CHECKMS, WAITMS, ASYNCMS, SYNCMS, 
OPENDR, WRITDR, READDR, CLOSDR, CHECKDR, WATTDR, ASYNCDR, SYNCDR 
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NAME 

SVOLPRC - Initializes/terminates special BOV/EOV processing (obsolete) 

SYNOPSIS 

CALL S\OLVRC(dn4flag) 

DESCRIPTION 

dn Type INTEGER variable, expression, or constant The name of the dataset as a Hollerith 

constant or unit number of the dataset 

iflag Type INTEGER variable 

=1 Turn BOV/EOV processing ON 
=0 Turn BOV/EOV processing OFF 

SVOLPRC should be called to inform the operating system that you wish to perform extra processing 
when the end of a tape volume is reached. Calling SVOLPRC with the OFF flag indicates that the user 
program no longer needs to be notified of EOV conditions. COS does not perform automatic volume 
switching following an SVOLPRC call with the ON flag set. 

NOTE 

Cray Research discourages the use of the CONTPIO, PROCBOV, PROCEOV, SWITCHV, and SVOL- 
PROC routines. Instead, use CLOSEV, SETSP, STARTSP, and ENDSP when creating special tape pro- 
cessing routines to handle end-of-volume conditions. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

CHECKTP, CONTPIO, PROCBOV, PROCEOV, SWITCHV 
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NAME 

SWUCHV - Switches tape volume 

SYNOPSIS 

CALL SWrrCHV(dn,iprc,istat,icbuf) 

DESCRIPTION 

dn Type INTEGER variable, expression, or constant. The name of the dataset as a Hollerith 

constant or unit number of the dataset. 

iprc Type INTEGER variable. Processing option at EOV. 

- 1 Continue processing at EOV 

= 0 Stop at EOV and return tape status information 

istai Type INTEGER variable 

No status 
= 0 EOV 
= 1 Tape off reel 
= 2 Tape mark detected 
= 3 Blank tape detected 

icbitf Type INTEGER variable. Circular I/O buffer status. 

= 0 Circular I/O buffer empty 
= 1 Circular I/O buffer not empty 

The user program can use SWITCHV to switch to the next tape volume and to check on a tape dataset* s 
condition. 

NOTE 

Cray Research discourages the use of the CONTPIO, PROCBOV, PROCEOV, SWITCHV, and SVOL- 
PROC routines. Instead, use CLOSEV, SETSP, STARTSP, and ENDSP when creating special tape pro- 
cessing routines to handle end-of-volume conditions. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

CHECKTP, CONTPIO, PROCBOV, PROCEOV, SVOLPRC 
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NAME 

SYNCH - Synchronizes the program and an opened tape dataset 

SYNOPSIS 

CALL SYNCH(dnj>djstai) 

DESCRIPTION 

dn Name of the dataset or unit number to be synchronized. Must be a type integer variable or an 
array element containing Hollerith data of not more than 7 characters. This parameter should 
be of the form WL. 

pd Processing direction: 

=0 Input dataset 

*0 Output dataset 

istat Return conditions. This parameter returns errors and warnings from the position routine. 

=0 Dataset successfully synchronized 

*0 Error or warning encountered during request, as follows: 
=1 Execution error 
=2 Dataset is not a tape dataset. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

GETTP, SETTP, GETPOS, SETPOS 
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NAME 

SYNCMS, SYNCDR - Sets I/O mode for random access routines to synchronous 

SYNOPSIS 

CALL SYWCMSidniUerr]) 
CALL SYNCDRCdWCferr]) 

DESCRIPTION 

dn The name of the dataset as a Hollerith constant or the unit number of the dataset. Hollerith 

constant dataset names must be from 1 to 7 characters. Specify a type integer variable, 
expression, or constant 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

SYNCMS/SYNCDR, ierr returns any error codes to you. If ierr>O t no error messages are 
put into the logfile. Otherwise, an error code is returned, and the message is added to the 
job's logfile. 

On output from SYNCMS/SYNCDR: 
ierr=Q No errors detected 

<0 Error detected ierr contains one of the following eitor codes: 



Error Codes 


-1 


The dataset name or unit number is invalid 


-15 


OPENMS/OPENDR was not called on this dataset 



All I/O operations wait for completion. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

OPENMS, WRITMS, READMS, CLOSMS, FINDMS, CHECKMS, WATTMS, ASYNCMS, OPENDR, 
WRITDR, READDR, CLOSDR, STINDR, CHECKDR, WAITDR, ASYNCDR, STINDX 
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NAME 

WAITMS, WATTDR - Waits for completion of an asynchronous I/O operation 

SYNOPSIS 

CALL WATTMS(dn t istatUerr]) 
CALL WATTDR(dn4statUerr)) 

DESCRIPTION 

dn The name of the dataset as a Hollerith constant or the unit number of the dataset. Hollerith 

constant dataset names must be from 1 to 7 characters. Specify a type integer variable, 
expression, or constant 

istat Dataset Error flag. Specify a type integer variable. 

istat=Q No error occurred during the asynchronous I/O operation 
=1 Error occurred during the asynchronous I/O operation 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

WATTMS/WAITDR, ierr returns any error codes to you. If ierr>O f no error messages are 
put into the logfile. Otherwise, an error code is returned, and the message is added to the 
job's logfile. 

On output from WATTMSAVAITDR: 

ierr=Q No errors detected 

<0 Error detected, ierr contains one of the error codes described 
in the following table: 



Error Codes 


-1 


The dataset name or unit number is invalid 


-15 


OPENMS/OPENDR was not called on this dataset 



A status flag is returned to you, indicating whether or not the I/O on the specified dataset was com- 
pleted without error. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

OPENMS, WRITMS, READMS, CLOSMS, FINDMS, CHECKMS, ASYNCMS, SYNCMS, OPENDR, 
WRITDR, READDR, CLOSDR, STINDR, CHECKDR, ASYNCDR, SYNCDR, STINDX 
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NAME 

WCHECK - Checks word-addressable file status 

SYNOPSIS 

CALL WCHECK(dn,statUerr]) 

DESCRIPTION 

dn Name of the dataset as a Hollerith constant, or the unit number of the dataset (for example, 

dn=l corresponds to FT07). Hollerith constant dataset names must be from 1 to 7 charac- 
ters. Specify a type integer variable, expression, or constant. 

stat Status code 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

WCHECK, ierr returns any error codes to you. If ierr is not supplied, an error aborts the 
job. 

On output from WCHECK: 

stat=Q No file activity 

=1 File is active when called 

ierr=0 No errors detected 

= 5 Check on a file that is not open 
=-1 Invalid unit number 
=-6 Invalid dataset name 



NOTES 

Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are 
single threaded. Some library routines, however, must be locked at the user level if they are used by 
more than one task. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

PUTWAU, GETWAU 
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NAME 

WCLOSE - Closes a word-addressable, random-access dataset 

SYNOPSIS 

CALL WCLOSE(dnUerr]) 

DESCRIPTION 

dn Name of the dataset as a Hollerith constant, or the unit number of the dataset Specify a 

type integer variable, expression, or constant 

ierr Error control and code. Specify a type integer variable, expression, or constant If you 

supply ierr on the call to WCLOSE, ierr returns any error codes to you. If ierr is not sup- 
plied, an error aborts the job. 

On output from WCLOSE: 
iern=0 No errors detected 
=^1 Invalid unit number 
=-6 Invalid dataset name 

WCLOSE finalizes the additions and changes to the word-addressable, random-access dataset and closes 
the dataset 

IMPLEMENTATION 

This routine is available to users of both the COS and UMCOS operating systems. 

SEE ALSO 

WOPEN, PUTWA, APUTWA, GETWA, SEEK 
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NAME 

WCLOSEU - Closes a word-addressable, unbuffered random-access dataset 

SYNOPSIS 

CALL WCLOSEU(rfn[^rr]) 

DESCRIPTION 

dn Name of the dataset as a Hollerith constant, or the unit number of the dataset. Specify a 

type integer variable, expression, or constant. 

ierr Error control and code. Specify a type integer variable, expression, or constant. If you 

supply ierr on the call to WCLOSE, ierr returns any error codes to you. If ierr is not sup- 
plied, an error aborts the job. 

On output from WCLOSE: 
ie/r=0 No errors detected 
=-1 Invalid unit number 
=-6 Invalid dataset name 

WCLOSEU finalizes the additions and changes to the word-addressable, random-access dataset and 
closes the dataset* 

IMPLEMENTATION 

This routine is available only to users of the COS operating system, 

SEE ALSO 

WOPEN, PUTWA, APUTWA, GETWA, SEEK 
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NAME 

WNLFLAG, WNLDELM, WNLSEP, WNLREP - Provides user control of output format 

SYNOPSIS 

CALL WNLFLAG(ctor) 
CALL WNLDELM(c/wr) 
CALL WNLSEP(char) 
CALL WNLREP(ctor) 

DESCRIPTION 

char For WNLFLAG, the first ASCII character of the first line. Default is blank. 
For WNLDELM, a NAMELIST delimiter. Default is '&'. 
For WNLSEP, a NAMELIST separator. Default is 7. 
For WNLREP, a NAMELIST replacement character. Default is '='. 

WNLFLAG changes the character written in column 1 of the first line from blank to char. Typically, 
char is used for carriage control if the output is to be listed, or for forcing echoing if the output is to 
be used as input for NAMELIST reads. 

WNLDELM changes the character preceding the group name and END from *&' to char. 

WNLSEP changes the separator character immediately following each value from y to char. 

WNLREP changes the replacement operator that comes between name and value from *=* to char. 

In each of these subroutines, char can be any ASCII character specified by ILx or IRjc. No checks are 
made to determine if char is reasonable, useful, or consistent with other characters. If the default char- 
acters are changed, use of the output line as NAMELIST input might not be possible. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

RNL, RNLECHO, RNLSKIP, RNLTYPE WNLLINE, WNLLONG 
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NAME 

WNLLINE - Allows each NAMELIST variable to begin on a new line 

SYNOPSIS 

CALL WNLLINE(va/«e) 

DESCRIPTION 

value =0 No new line 

=1 New line for each variable 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

RNL, RNLECHO, RNLSKIP, RNLTYPE WNL, WNLLONG 
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NAME 

WNLLONG - Indicates output line length 

SYNOPSIS 

CALL WNLLONG(length) 

DESCRIPTION 

length Output line length; %<length<16l or tength=-l (-1 specifies default of 133 unless the unit is 
102 or SPUNCH, in which case the default is 80). 

IMPLEMENTATION 

This routine is available to users of both the COS and UNTCOS operating systems. 

SEE ALSO 

RNL, RNLECHO, RNLSKIP, RNLTYPE WNL, WNLLINE 
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NAME 

WOPEN - Opens a word-addressable, random-access dataset 

SYNOPSIS 

CALL WOPEN(dn t blocks,istatsLierr]) 

DESCRIPTION 

dn Name of the dataset as a Hollerith constant, or the unit number of the dataset (for example, 

7 corresponds to FT07). Hollerith constant dataset names must be from 1 to 7 characters. 
Specify a type integer variable, expression, or constant 

blocks The maximum number of 512-word blocks that the word-addressable package can use for a 
buffer. Specify a type integer variable, expression, or constant. 

istats Specify a type integer variable, expression, or constant. If istats is nonzero, statistics about 
the changes and accesses to the dataset dn are collected. (See the following table for infor- 
mation about the statistics that are collected) Under COS, these statistics are written to 
dataset SSTATS and can be to $OUT by using the following control statements or their 
equivalents after the dataset has been closed by WCLOSE. 

REWIND,DN~$STATS. 

COPYDJ=$STATS,0=$OUT. 

Under UNICOS, statistics are written to stderr. 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

WOPEN, ierr returns any error codes to you. If ierr is not supplied, an error aborts the 
job. 

On output from WOPEN: 

ierr=Q No errors detected 
-1 Invalid unit number 

-2 Number of datasets has exceeded memory size availability 
-6 Invalid dataset name 

WOPEN opens a dataset and specifies it as a word-addressable, random-access dataset that can be 
accessed or changed with the word-addressable I/O routines. The WOPEN call is optional. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

WCLOSE, PUTWA, APUTWA, GETWA, SEEK 
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MESSAGES 



WOPEN Statistics 


Message 


Description 


BUFFERS USED = 


Number of 512-word buffers used 
by this dataset 


TOTAL ACCESSES = 


Number of accesses. This is the 
sum of the GETWA and PUTWA calls. 


GETS = 


Number of times the user called GETWA 


PUTS = 


Number of times the user called PUTWA 


FINDS = 


Number of times the user called SEEK 


HITS = 


Number of times word addresses 
desired were resident in memory 


MISSES = 


Number of times no word addresses 
desired were resident in memory 


PARTIAL HITS = 


Number of times that some but not 
all of the word addresses desired 
were in memory 


DISK READS = 


Number of physical disk reads done 


DISK WRITES = 


Number of times a physical disk 
was written to 


BUFFER FLUSHES = 


Number of times buffers were flushed 


WORDS READ = 


Number of words moved from buffers 
to user 


WORDS WRITTEN = 


Number of words moved from user 
to buffers 


TOTAL WORDS = 


Sum of WORDS READ and WORDS WRITTEN 


TOTAL ACCESS TIME = 


Real time spent in disk transfers 


AVER ACCESS TIME = 


TOTAL ACCESS TIME divided by the sum 
of DISK READS and DISK WRITES 


EOD BLOCK NUMBER = 


Number of the last block of the dataset 


DISK WORDS READ = 


Count of number of words moved from 
disk to buffers 


DISK WDS WRITTEN = 


Count of number of words moved from 
buffers to disk 


TOTAL DISK XFERS = 


Sum of DISK WORDS READ 
and DISK WORDS WRITTEN 


BUFFER BONUS % = 


TOTAL WORDS divided by value TOTAL 
DISK XFERS multiplied by 100 
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NAME 

WOPENU - Opens a word-addressable, random-access dataset, unbuffered 
SYNOPSIS 

CALL WOPENVidnMocksMatslierrlipru]]) 
DESCRIPTION 

dn Name of the dataset as a Hollerith constant, or the unit number of the dataset (for example, 

7 corresponds to FT07). Hollerith constant dataset names must be from 1 to 7 characters. 
Specify a type integer variable, expression, or constant. 

blocks Size of buffer to use for this dataseL Since this is a special unbuffered dataset, this param- 
eter is ignored. 

istats Specify a type integer variable, expression, or constant If istats is nonzero, statistics about 
the changes and accesses to the dataset dn are collected. (See the following table for infor- 
mation about the statistics that are collected.) Under COS, these statistics are written to 
dataset SSTATS and can be to $OUT by using the following control statements or their 
equivalents after the dataset has been closed by WCLOSEU. 

REWIND,DN=$STATS. 

COPYDJ=$STATS,0=$OUT. 

Under UNICOS, statistics are written to stderr. 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

WOPENU, ierr returns any error codes to you. If ierr is not supplied, an error aborts the 
job. 

On output from WOPENU: 

ierr=0 No errors detected 
-1 Invalid unit number 

-2 Number of datasets has exceeded memory size availability 
-6 Invalid dataset name 

ipru When you use WOPENU, the physical record size is always 512 words. This parameter is 

ignored if supplied and is provided only for compatibility with other calls. 

WOPENU opens a dataset and specifies it as a word-addressable, random-access dataset that can be 
accessed or changed with the word-addressable I/O routines. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

WCLOSEU, PUTWAU, GETWAU, SEEK 
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MESSAGES 



WOPENU Statistics 


Message 


Description 


BUFFERS USED = 


Number of 512-word buffers used 
by this dataset 


TOTAL ACCESSES = 


Number of accesses. This is the 
sum of the GETWA and PUTWA calls. 


GETS = 


Number of times the user called GETWA 


PUTS * 


Number of times the user called PUTWA 


FINDS = 


Number of times the user called SEEK 


HITS = 


Number of times word addresses 
desired were resident in memory 


MISSES = 


Number of times no word addresses 
desired were resident in memory 


PARTIAL HITS = 


Number of times that some but not 
all of the word addresses desired 
were in memory 


DISK READS = 


Number of physical disk reads done 


DISK WRITES = 


Number of times a physical disk 
was written to 


BUFFER FLUSHES = 


Number of times buffers were flushed 


WORDS READ = 


Number of words moved from buffers 
to user 


WORDS WRITTEN = 


Number of words moved from user 
to buffers 


TOTAL WORDS = 


Sum of WORDS READ and WORDS WRITTEN 


TOTAL ACCESS TIME = 


Real time spent in disk transfers 


AVER ACCESS TIME = 


TOTAL ACCESS TIME divided by the sum 
of DISK READS and DISK WRITES 


EOD BLOCK NUMBER = 


Number of the last block of the dataset 


DISK WORDS READ = 


Count of number of words moved from 
disk to buffers 


DISK WDS WRITTEN = 


Count of number of words moved from 
buffers to disk 


TOTAL DISK XFERS = 


Sum of DISK WORDS READ 
and DISK WORDS WRITTEN 


BUFFER BONUS % = 


TOTAL WORDS divided by value TOTAL 
DISK XFERS multiplied by 100 
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NAME 

WRITE, WRTTEP - Writes words, full or partial record mode 

SYNOPSIS 

CALL WRiTE(dn f word t count t ubc) 
CALL WWLTEP(dn,word,count,ubc) 

DESCRIPTION 

dn Unit number or file name, seven characters or less and specified as a Hollerith 

word Data area containing words 

count Word count For WRITE, a value of 0 causes an end-of record (EOR) record control word 
to be written. 

ubc Optional unused bit count Number of unused bits contained in the last word of the record. 

In routines where words are written, the number of words specified by the count are transmitted from 
the area beginning at the first word address and are written in the I/O buffer. These routines are 
intended to write to COS blocked datasets. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

READ, READP, READC, READCP, READIBM, WRITEC, WRITECP, WRITIBM, SKBPBAD, ACPTBAD 
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NAME 

WRITEC, WRITECP - Writes characters, full or partial record mode 

SYNOPSIS 

CALL WRlTEC(dn t char t count) 
CALL WWTEC 1 P(dn,char t count) 

DESCRIPTION 

dn Dataset name or unit number 

char Data area containing characters 
count Character count 

Write character routines pack characters into the I/O buffer for the dataset The count specifies the 
number of characters packed, These characters originate from the user area defined at the first word 
address, which is 1 character per source word (right-justified). Blank compression is performed on the 
characters written out. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
SEE ALSO 

READ, READP, RE ADC, READCP, READIBM, WRITE, WRITEP, WRITIBM, SKIPBAD, ACPTBAD 
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NAME 



WRrnBM - Writes two IBM 32-bit floating-point words from each Cray 64-bit word 



SYNOPSIS 



CALL W«nmM{dnfwayalue increment) 



DESCRIPTION 



dn 



Dataset name or unit number 



fwa 
value 



First word address (FWA) of the user data area 
Number of values to be written 



increment Increment of the source (Cray) words written 
On exit, IBM 32-bit words are written to the unit 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

READ, READP, READC, READCP, READIBM, WRITE, WRTTEP, WRTTEC, WRTTECP, SKIPBAD, 
ACPTBAD 
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NAME 

WRITMS, WRTTDR - Writes to a random access dataset on disk 
SYNOPSIS 

CALL \VtmMS(dn,ubi$ t n t irec t rrflagA4err]) 
CALL WKH1)R(dn t ubi$'>n4rec,rrfhgAjerr]) 

DESCRIPTION 

dn The name of the dataset as a Hollerith constant or the unit number of the dataset (for exam- 

ple, dn=H corresponds to dataset FT07). Hollerith constant dataset names must be from 1 to 
7 characters. Specify a type integer variable, expression, or constant. 

ubitff The location of the first word in the user program to be written to the record. User- 
specified type. 

n The number of words to be written to the record. Specify a type integer variable, expres- 

sion, or constant n contiguous words from memory, beginning at ubuff, are written to the 
dataset record. Since COS unblocked-dataset I/O is in multiples of 512 words, it is recom- 
mended that n be a multiple of 512 words when speed is important However, the random 
access dataset I/O routines support record lengths other than multiples of 512 words. 
WRTTDR rounds n up to the next multiple of 512 words, if necessary. 

irec The record number or record name of the record to be written. Specify a type integer vari- 

able, expression, or constant. A record name is limited to a maximum of 8 characters. For 
a numbered index, irec must be between 1 and the length of the index declared in the 
OPENMS/OPENDR call. For a named index, irec is any 64-bit entity you specify. 

rrflag A flag indicating record rewrite control. Specify a type integer variable, expression, or con- 
stant rrflag can be one of the following codes: 

0 Write the record at EOD. 

1 If the record already exists, and the new record length is less than or equal to the 
old record length, rewrite the record over the old record. If the new record length 
is greater than the old, abort the job step or return the error code in ierr. If the 
record does not exist, the job aborts or the error code is returned in ierr. 

-1 If the record exists, and its new length does not exceed the old length, write the 
record over the old record. Otherwise, write the record at EOD. 

s A sub-index flag. Specify a type integer variable, expression, or constant (The implemen- 

tation of this parameter has been deferred.) 

ierr Error control and code. Specify a type integer variable. If you supply ierr on the call to 

WRITMS/WRITDR, ierr returns any error codes to you. If ierr>0> no error messages are 
put into the log file. Otherwise, an error code is returned, and the message is added to the 
job's log file. 

On output from WRITMS/WRITDR: 
ierr=0 No errors detected 

<0 Error detected, ierr contains one of the error codes described 
in the following table: 
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Error Codes 


-1 


The dataset name or unit number is invalid 


-6 


The user-supplied named index is invalid 


-7 


Trip tiamfvl nwvH ii^Hpy firrav full 


■8 


The index number is greater than the maximum 
on the dataset 


-9 


Rewrite record exceeds the original 


-15 


OPENMS/OPENDR was not called on this dataset 


-17 


The index entry is less than or equal to 0 
in the users index array 


-18 


The user-supplied word count is less than or 
equal to 0 


-19 


The user-supplied index number is less than or 
equal to 0 



WRITMS and WRITDR write data from user memory to a record in a random access dataset on disk 
and updates the current index. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 

NOTE 

Most of the routines in the run-time libraries are reentrant or have internal locks to ensure that they are 
single threaded. Some library routines, however, must be locked at the user level if they are used by 
more than one task. 

WRITMS and WRITDR are not internally locked. You must lock each call to these routines if they are 
called from more than one task. 

EXAMPLES 

The following examples show some of the features and uses of random access dataset routines. 

Example 1 - In the program SORT, a sequence of records is read in and then printed out as a sorted 
sequence of records. 

1 PROGRAM SORT 

2 INTEGER IARRAY (512) 

3 INTEGER INDEX (512), KEYS (100) 

4 CALL OPENMS ('SORT'.INDEX^S.l) 

5 N=50 

C READ IN RANDOM ACCESS RECORDS FROM UNIT "SORT" 

6 DO 21 1=1 ,N 

7 READ(5,1000) (IARR AY(J) J=l ,5 12) 

8 NAME=IARRAY(1) 

9 KEYS(I)=IARRAY(1) 

10 CALL WRITMS (*SORT'JARRAY,512^AME,0) 
21 CONTINUE 

C SORT KEYS ALPHABETICALLY IN ASCENDING ORDER USING 
C EXCHANGE SORT 

12 DO 23 I=1,N-1 

13 MIN=I 
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14 J=I+1 

15 DO 22 K=J,N 

16 IF (KEYS(K).LT.KEYS(MIN)) MIN=K 

22 CONTINUE 

18 IB=KEYS(I) 

19 KEYS(I)=KEYS(MIN) 

20 KEYS(M1N)=IB 

23 CONTINUE 

C WRITE OUT RANDOM ACCESS RECORDS IN ASCENDING 
C ALPHABETICAL ORDER 

22 DO 24 I=1,N 

23 NAME=KEYS(I) 

24 CALL READMS ('SORT\IARRAY,512,NAME) 

25 WRITE(6,5120) (IARRAY(J)J=1,512) 

24 CONTINUE 

1000 FORMAT (" ") 

5120 FORMAT (IX," ") 

29 CALL CLOSMS ('SORT*) 

30 STOP 

31 END 

In this example, the random access dataset is initialized as shown in line 4. Lines 6 through 1 1 show 
that a record is read from unit 5 into array IARRAY and then written as a record to the random access 
dataset SORT. The first word of each record is assumed to contain an 8-character name to be used as 
the name of the record. 

Lines 12 through 21 show that the names of the records are sorted in the array KEYS. Lines 22 
through 26 show that the records are read in and then printed out in alphabetical order. 

Example 2 - The programs INITIAL and UPDATE show how the random access dataset might be 
updated without the usual search and positioning of a sequential access dataset. 

Program INITIAL: 

1 PROGRAM INITIAL 

2 INTEGER IARRA Y(5 12) 

3 INTEGER INDEX (512) 
C 

C OPEN RANDOM ACCESS DATASET 

C THIS INITIALIZES THE RECORD KEY "INDEX" 

C 

4 CALL OPENMS ('MASTERMNDEX.lOl.l) 
C 

C READ IN RECORDS FROM UNIT 6 AND 

C WRITE THEM TO THE DATASET "MASTER" 

C 

5 DO 101=1,50 

6 RE AD(6,600) (IARRAY(J) J=l ,5 12) 

7 NAME=IARRAY(1) 

8 CALL WRITMS ('MASTER MARRAY.5 12,NAME,0,0) 
10 CONTINUE 
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C 

C CLOSE "MASTER" AND SAVE RECORDS FOR UPDATING 
C 

10 CALL CLOSMS ('MASTER') 
600 FORMAT (IX,' ') 

12 STOP 

13 END 



Program UPDATE: 

1 PROGRAM UPDATE 

2 INTEGER ENEWRCD(512) 

3 INTEGER INDX (512) 
C 

C OPEN RANDOM ACCESS DATASET CREATED IN THE 

C PREVIOUS PROGRAM "INITIAL" 

C 

C INDX WILL BE WRITTEN OVER THE OLD RECORD KEY 
C 

4 CALLOPENMS ('MASTER \INDX,101,1) 
C 

C READ IN NUMBER OF RECORDS TO BE UPDATED 
C 

5 READ (6,610) N 
C 

C READ IN NEW RECORDS FROM UNIT 6 AND 

C WRITE THEM IN PLACE OF THE OLD RECORD THAT HAS 

C THAT NAME 

C 

6 DO 10I=1,N 

7 READ(6,600)(INEWRCD(J),J=1,512) 

8 N AME=INEWRCD( 1 ) 

9 CALL WRITMS ('MASTER \INEWRCD,512,NAME,1,0) 

10 CONTINUE 
C 

C CLOSE "MASTER" AND SAVE NEWLY UPDATED RECORDS 

C FOR FURTHER UPDATING 

C 

1 1 CALL CLOSMS ("MASTER") 

12 600 FORMAT (IX," ") 

13 610 FORMAT (IX," ") 

14 STOP 

15 END 

In the preceding example, program INITIAL creates a random access dataset on unit MASTER; program 
UPDATE then replaces particular records of this dataset without changing the remainder of the records. 
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Line 10 shows that the call to CLOSMS at the end of INITIAL caused the contents of INDEX to be written to 
the random access dataset. 

Line 4 shows that the call to OPENMS at the beginning of UPDATE has caused the record key of the random 
access dataset to be written to INDX. The random access dataset and INDX are now the same as the random 
access dataset and INDEX at the end of INITIAL. 

Lines 6 through 10 show that certain records are replaced. 

Example 3 - The program SNDYMS is an example of the use of the secondary index capability, using 
STINDX. In this example, dummy information is written to the random access dataset. 

PROGRAM SNDYMS 
IMPLICIT INTEGER (A-Y) 

DIMENSIONPINDEX(20),SINDEX(30)ZBLIFFR(50) 
DATA PLEN.SLEN .RLEN /20.30.50/ 
C OPEN THE DATASET. 

CALL OPENMS (1,PINDEX,PLEN,0,ERR) 
IF (ERR.NE.0) THEN 

PRINT*,' Error on OPENMS , err=' JERR 

STOP1 
ENDIF 

C LOOP OVER THE 20 PRIMARY INDICES. EACH TIME 
C A SECONDARY INDEX IS FULL, WRITE THE 
C SECONDARY INDEX ARRAY TO THE DATASET. 

DO 40 K=1,PLEN 
C ZERO OUT THE SECONDARY INDEX ARRAY. 

DO10l=l,SLEN 
10SINDEX(I)=0 
C CALL STBMDX TO CHANGE INDEX TO SINDEX. 

CALL STINDX (1,SINDEX,SLEN,0,ERR) 

IF (ERR.NE.0) THEN 
PRINT*,' Error on STINDX, err=*,ERR 
STOP 2 

ENDIF 
C WRITE SLEN RECORDS. 

DO30J=l.SLEN 
C GENERATE A RECORD LENGTH BETWEEN 1 AND RLEN. 

TRLEN=MAXO(1FIX{RANF(0)*FLOAT(RLEN)),1) 
C FILL THE "DATA" ARRAY WITH RANDOM FLOATING POINT 
C NUMBERS. 

DO 20 I=1,TRLEN 

20 ZBUFFR(I)=(J+SIN(FLOAT(I)))**(1.+RANF(0)) 
CALL WRITMS ( 1 .ZBUFFR ,TRLENJ,-1 .DUMMY JERR) 
IF (ERR.NE.0) THEN 

PRINT*,' Error on WRITMS, err=\ERR 

STOP 3 
ENDIF 

30 CONTINUE 
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C "TOGGLE" THE INDEX BACK TO THE MASTER AND 
C WRITE THE SECONDARY INDEX TO THE DATASET. 

CALL STINDX (l.PINDEX.PLEN.O) 
C NOTE THE ABOVE STINDX CALL DOES NOT USE THE 
C OPTIONAL ERROR PARAMETER, AND WILL ABORT 
C IF STINDX DETECTS AN ERROR. 

CALL WRITMS (1,SINDEX,SLEN,K,-1J>UMMY3RR) 
IF (ERR.NE.0) THEN 
PRINT*,' Error on STINDX, err=' JERR 
STOP 4 
ENDIF 
40 CONTINUE 
C CLOSE THE DATASET. 
CALL CLOSMS (1.ERR) 
IF (ERR.NE.0) THEN 
PRINT*,' Error on CLOSMS, err=',ERR 
STOPS 
ENDIF 

STOP 'Normal' 
END 
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13. DATASET UTILITY ROUTINES 



The dataset utility routines manipulate datasets for use by a program unit. The following routines are 
ANSI standard Fortran routines (except LENGTH and UNIT, which are CFT extensions) and are 
described in the Fortran (CFT) Reference Manual, publication SR-0009 and the CFT77 Reference Manual, 



publication SR-0018. 




Routine 


Description 


OPEN 


Connects a dataset to a unit 


CLOSE 


Terminates the connection of a dataset to a unit 


INQUIRE 


Returns status of a unit or a dataset 


BACKSPACE 


Positions a dataset after the previous end-of-record (EOR) 


REWIND 


Rewinds a dataset 


END FILE 


Writes end-of-file (EOF) on a file 


UNIT 


Returns I/O status upon completion of an I/O operation 


LENGTH 


Returns the number of Cray words transferred 



IMPLEMENTATION 

The preceding ANSI standard Fortran routines are available to users of both the COS and UNICOS 
operating systems. 

The following routine types are described by entries in this section: copy, skip, dataset positioning, ter- 
mination, and I/O status routines. 

Copy routines copy a specified number of records or files from one dataset to another, copy one dataset 
to another, and copy a specified number of sectors or all data to end-of-data (EOD). 

Skip routines direct the system either to bypass a specified number of records, files, sectors, or all data 
from the current position of a named dataset, or to position a blocked dataset at EOD. 

The termination routine EODW terminates a dataset by writing EOF, EOR, and EOD. It also clears the 
uncleared End-of-file flag (UEOF) in the Dataset Parameter Table (DSP). 

The last group of dataset utility routines return I/O information. 

The following table contains the name, purpose, and entry for each dataset utility routine. 
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Dataset Utility Rout] 


nes 


Purpose 


Name 


Entry 


Position a dataset after the previous 
EOF and clear the UEOF flag in the 
DSP 


BACKFILE 


BACKFILE 


Copy records from one dataset to 
another 


COPYR 
COPYSR 




Copy files from one dataset to 
another 


pnpvi? 

k^KJmT I P 

COPYSF 


Copy one dataset to another 


COPYD 
COPYSD 


Copy sectors or all data to EOD 


CClPVll 


C OP VI I 


Tprminfltf* a Hafs^f Hv u/rifintr POD 

EOF, and EOR and clear the UEOF flag 
in the DSP 






Return the real value EOF status and 
clear the UEOF flag in the DSP 


EOF 
IEOF 


EOF 


Return the integer value EOF status and 
clear the UEOF flag in the DSP 


Return EOF and EOD status 


IOSTAT 


IOSTAT 


Return the current size of a dataset 
in 5 12- word blocks 


NUMBLKS 


NUMBLKS 


Skip records 


SKIPR 


SKIPR 


Skip files 


SKIPF 


Position a blocked dataset at EOD 


SKIPD 


SKIPD 


Skip sectors in a dataset 


SKIPU 


SKIPU 
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NAME 

BACKFILE - Positions a dataset after the previous EOF 

SNYOPSIS 

CALL BACKFILE(<to) 

DESCRIPTION 

dn Dataset name or unit number of the dataset to be repositioned 

BACKFILE positions a dataset after the previous end-of-file (EOF) and then clears the UEOF flag in the 
Dataset Parameter Table (DSP). 

This function is nonoperational if the dataset is at beginning-of-data (BOD). 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 



SR-0113 



13-3 



D 



COPYR (3COS) 



COPYR(3COS) 



NAME 

COPYR, COPYF, COPYD - Copies records, files, or a dataset from one dataset to another 

SYNOPSIS 

CALL CQVYVL{idn>odn,recordlistai\) 
CALL COPY$R(idn,odn t record t $count[,istat]) 

CALL COPYF(idns>dnfilelistat]) 
CALL COPYSF(idn,odnfile,scount[,istat]) 

CALL COPYD(idn,odn) 
CALL COPYSD(idn,odnjcount) 

DESCRIPTION 

idn Dataset name or unit number of the dataset to be copied 

odn Dataset name or unit number of the dataset to receive the copy 

record Number of records to be copied 

file Number of files to be copied 

scount Number of ASCII blanks to be inserted at the beginning of each line of text 

istat A two-element integer array that returns the number of records copied in the first element 
and the number of files copied in the second element. (For COPYR, the number of files 
copied is always 0.) istat is an optional parameter. If present, only fatal messages are writ- 
ten to the log file. 

COPYR and COPYF copy a specified number of records or files from one dataset to another, starting at 
the current dataset position. Following the copy, the datasels are positioned after the EOR or EOF for 
the last record or file copied. 

COPYD copies one dataset to another, starting at their current positions. Following the copy, both 
datasets are positioned after the EOF of the last file copied. The EOD is not written to the output- 
dataset. 

COPYSR, COPYSF, and COPYSD are the same as COPYR, COPYF, and COPYD, respectively, except 
that the copied data is preceded by scount blanks. 

CAUTION 

These routines are not intended for use with foreign dataset translation. When foreign dataset record 
boundaries coincide with Cray dataset record boundaries, proper results may be expected. However, it 
is difficult in general to determine when such coincidences occur. Use of these routines with foreign 
datasets is discouraged* 

IMPLEMENTATION 

These routines are available only to users of the COS operating system. 

SEE ALSO 

COPYU, SKIPR, SKIPD, SKIPU 
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NAME 

COPYU - Copies either specified sectors or all data to EOD 

SYNOPSIS 

CALL CO¥YU(idn,odn,nsUstat]) 

DESCRIPTION 

idn Name of the unblocked dataset to be copied 

odn Name of the unblocked dataset to receive the copy 

ns Decimal number of sectors to copy. If the unblocked dataset contains fewer than ns sec- 

tors, the copy terminates at EOD. The entire dataset is copied if -1 is specified. If COPYU 
is called with only two parameters, only one sector is copied. 

istat An integer array or variable that returns the number of sectors copied, istat is an optional 
parameter. If istat is present, only fatal messages are written to the log file. 

Copying begins at the current position on both datasets. Following the copy, the datasets are positioned 
after the last sector copied. 

CAUTION 

This routine is not intended for use with foreign dataset translation. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

COPYR, SKIPU 
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NAME 

EODW - Terminates a dataset by writing EOD, EOF, and EOR 

SYNOPSIS 

CALL EODW(<2») 

DESCRIPTION 

dn Dataset name or unit number of the dataset to be terminated 

EODW writes an EOD, and, if necessary, an EOF and an EOR. The UEOF flag in the DSP is cleared. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

EOF, IEOF - Returns real or integer value EOF status 
SYNOPSIS 

iexit=IEOF(dn) 
DESCRIPTION 



rexit 



lexit 



dn 



-1.0 
0.0 
+1.0 



EOD on the last operation 

Neither EOD nor EOF on the last operation 

EOF on the last operation 



-1 EOD on the last operation 

0 Neither EOD nor EOF on the last operation 

+1 EOF on the last operation 

Dataset name or unit number 



EOF returns one of the above real values when checking the EOF status. IEOF returns one of the above 
integer values when checking the EOF status. Under COS, both routines clear the UEOF flag in the DSP. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

IOSTAT - Returns EOF and EOD status 

SYNOPSIS 

iexit=10SrtAT(dn) 

DESCRIPTION 

iexit 0 No error 

1 Dataset at EOF (UEOF cleared) 

2 Dataset at EOD (UEOF cleared) 

dn Dataset name or unit number 

IMPLEMENTATION 

This routine is only available to users of the COS operating system. 
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NAME 

NUMBLKS - Returns the current size of a dataset in 5 12- word blocks 

SYNOPSIS 

vwfeNUMBLKS(<rti) 

DESCRIPTION 

val Number of blocks returned as an integer value. The value returned reflects only the data 

actually written to disk and does not take into account data still in the buffers. If the 
dataset is not local to the job, or has never been written to, a function value of 0 is 
returned A negative value indicates that the underlying system call failed. 

dn Dataset name or unit number 

IMPLEMENTATION 

This routine is available to users of the both the COS and UNICOS operating systems. 
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NAME 

SKIPD - Positions a blocked dataset at EOD 

SYNOPSIS 

CALL SKIPD(dn[ t istat]) 

DESCRIPTION 

dn Dataset name or unit number to be skipped. Must be a character constant, an integer vari- 

able, or an array element containing Hollerith data of not more than 7 characters. 

istat A two-element integer array that returns the number of records skipped in the first element 
and the number of files skipped in the second element, istat is an optional parameter. If it 
is present, only fatal messages are written to the log file. 

SKIPD directs the system to position a blocked dataset at EOD, that is, after the last EOF of the dataset. 
If the specified dataset is empty or is already at EOD, the call has no effect. 

CAUTION 

This routine is not intended for use with foreign dataset translation. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

COPYR, SKIPR, SKIPU 
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NAME 

SKIPR, SKIFF - Skip records or files 

SYNOPSIS 

CALL SKim(dn t record[ t istat]) 
CALL SKlPF(dnfilelistat]) 

DESCRIPTION 

dn Dataset name or unit number that contains the record or file to be slapped. Must be a char- 

acter constant, an integer variable* or an array element containing Hollerith data of not 
more than 7 characters. If dn is opened before SKIPR or SKIPF is called, dn must be 
opened to allow read or read/write access. 

record Decimal number of records to be skipped. The default is 1. If record is negative, SKIPR 
skips backward on dn. 

file Decimal number of files to be skipped. The default is 1. If file is negative, SKIPR skips 

backward on dn. If dn is positioned midfile, the partial file skipped counts as one file. 

istat A two-element integer array that returns the number of records skipped in the first element 
and the number of files skipped in the second element. (For SKIPR, the number of files 
skipped is always 0.) istat is an optional parameter. If it is present, only fatal messages 
are written to the log file. 

SKIPR directs the system to bypass a specified number of records from the current position of the 
named blocked dataset. 

SKIPR does not bypass EOF or beginning-of-data (BOD), If an EOF or BOD is encountered before 
record records have been bypassed when skipping backward, the dataset is positioned after the EOF or 
BOD. When skipping forward, the dataset is positioned after the last EOR of the current file. 

SKIPF directs the system to skip a specified number of files from the current position of the named 
blocked dataset 

SKIPF does not skip EOD or BOD. If a BOD is encountered before file files have been skipped when 
skipping backward, the dataset is positioned after the BOD. When skipping forward, the dataset is posi- 
tioned before the EOD of the current file. 

CAUTION 

These routines are not intended for use with foreign dataset translation. When foreign dataset record 
boundaries coincide with Cray dataset record boundaries, proper results may be expected. However, it 
is difficult in general to determine when such coincidences occur. Use of these routines with foreign 
datasets is discouraged. 

EXAMPLE 

If the dataset connected to unit FT07 is positioned just after an EOF, the following Fortran call positions 
the dataset after the previous EOF. If the dataset is positioned midfile, it is positioned at the beginning 
of that file. 

CALL SKIPFfFTOTVl) 
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IMPLEMENTATION 

These routines are available only to users of the COS operating system. 

SEE ALSO 

COPYR, SKIPD, SKIPU 
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NAME 

SKIPU - Skips a specified number of sectors in a dataset 

SYNOPSIS 

CALL SKIPU(dnM,*W|) 
DESCRIPTION 

dn Dataset name or unit number of the unblocked dataset to be bypassed. Must be an integer 

variable or an array element containing ASCII data of not more than 7 characters. 

ns Decimal number of sectors to bypass. The default value is 1. If ns is negative, SKIPU 

skips backward on dn. 

istat An integer array or variable that returns the number of sectors skipped, istat is an optional 

parameter. If it is present, only fatal messages are written to the logfile. 

SKIPU directs the system to bypass a specified number of sectors or all data from the current position 
of the named unblocked dataset. 

CAUTION 

This routine is not intended for use with foreign dataset translation. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

COPYU, SKIPR, SKIPD 
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14. MULTITASKING ROUTINES 



Multitasking routines create and synchronize parallel tasks within programs. They are grouped in the 
following categories: 

• Task routines 

• Lock routines 

• Event routines 

• History trace buffer routines 

• Barrier routines 

For further information on using these subprograms in a multitasking environment, see the CRAY Y-MP 
and CRAY X-MP Multitasking Programmer's Manual, publication SR-0222. 

TASK ROUTINES 

Task routines handle tasks and task-related information. 

TASK CONTROL ARRAY - Each user-created task is represented by an integer task control array, con- 
structed by the user program. At a minimum, the array must consist of 2 Cray words; however, a third 
word can be included. The three words composing the array contain the following information: 

LENGTH Length of the array in Cray words. The length must be set to a value of 2 or 3, 
depending on the optional presence of the task value field. Set the LENGTH field 
before creating the task. 

TASK ID A task identifier assigned by the multitasking library when a task is created This 
identifier is unique among active tasks within the job step. The multitasking library 
uses this field for task identification, but the task identifier is of limited use to the user 
program. 

TASK VALUE (optional field) 

This field can be set to any value before the task is created. If TASK VALUE is used, 
LENGTH must be set to a value of 3. The task value can be used for any purpose. Sug- 
gested values include a programmer-generated task name or identifier or a pointer to a 
task local-storage area. During execution, a task can retrieve this value with the 
TSKVALUE subroutine. 

The following example sets parameters for the task control array TASKARY: 

PROGRAM MULTI 
INTEGER TASKARY(3) 

C 

C SET TASKARY PARAMETERS 
TASKARY(1)=3 
TASKARY(3)='TASK 1' 

C 

END 
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TASK SUBROUTINES - The following (able contains the purpose, name, and entry of each task routine. 



Task Routines 


Purpose 


Name 


Entry 


Initiate a task 


TSKSTART 


TSKSTART 


Indicate whether a task exists 


TSKTEST 


TSKTEST 


Modify tuning parameters within the 
library scheduler 


TSKTUNE 


TSKTUNE 


Wait for a task to complete execution 


TSKWAIT 


TSKWAIT 


Retrieve the user identifier 
specified in the task control array 


TSKVALUE 


TSKVALUE 



LOCK ROUTINES 

Lock routines protect critical regions of code and shared memory. 

The following table contains the purpose, name* and entry of each lock routine. 



Lock Routines 


Purpose 


Name 


Entry 


Identify an integer variable to be 
used as a lock 


LOCKASGN 


LOCKASGN 


Set a lock and return control to 
the calling task 


LOCKON 


LOCKON 


Clear a lock and return control to 
the calling task 


LOCKOFF 


LOCKOFF 


Release the identifier assigned to 
a lock 


LOCKREL 


LOCKREL 


Test a lock to determine its state 
(locked or unlocked) 


LOCKTEST 


LOCKTEST 
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EVENT ROUTINES 

Event routines signal and synchronize between tasks. 

The following table contains the purpose, name, and entry of each event routine. 



Event Routines 


Purpose 


Name 


Entry 


Post an event and return control to 
the calling task 


EVPOST 


EVPOST 


Clear an event and return control to 
the calling task 


EVCLEAR 


EVCLEAR 


Identify a variable to be used as 
an event 


EVASGN 


EVASGN 


Release the identifier assigned to 
a task 


EVREL 


EVREL 


Test an event to determine its 
posted state 


EVTEST 


EVTEST 


Delay the calling task until an 
event is posted 


EVWAIT 


EVWAIT 



MULTITASKING HISTORY TRACE BUFFER ROUTINES 

The user-level routines for the multitasking history trace buffer can be called from a user program to 
control what is recorded in the buffer and to dump the contents of the buffer to a dataset. 

The following table contains the purpose, name, and entry of each multitasking history trace buffer rou- 
tine. 



Multitasking History Trace Buffer Routines 


Purpose 


Name 


Entry 


Modify parameters used to control 
which multitasking actions are 
recorded in the history trace buffer 


BUFTUNE 


BUFTUNE 


Write a formatted dump of the 
history trace buffer to a dataset 


BUFPRINT 


BUFPRINT 


Write an unformatted dump of the 
history trace buffer to a dataset 


BUFDUMP 


BUFDUMP 


Add entries to the history trace 
buffer 


BUFUSER 


BUFUSER 
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BARRIER ROUTINES 

A barrier is a synchronization point in an application, beyond which no task will proceed until a 
specified number of tasks have reached the barrier. 

The following table contains the purpose, name, and entry of each barrier routine. 



Barrier Routines 


Purpose 


Name 


Entry 


Identify an integer variable to use 
as a barrier 


BARASGN 


BARASGN 


Register the arrival of a task as 
a barrier 


BARSYNC 


BARSYNC 


Release the identifier assigned to 
a hairier 


BARREL 


BARREL 
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NAME 

BARASGN - Identifies an integer variable to use as a barrier 

SYNOPSIS 

CALL BARASGN(«ame,va/ii*) 

DESCRIPTION 

name Integer variable to be used as a barrio-. The library stores an identifier into this variable. 

Do not modify the variable after the call to BARASGN unless a call to BARREL first 
releases the variable. 

value The integer number of tasks, between 1 and 31 inclusive, must call BARSYNC with name 
before the barrier is opened and the waiting tasks allowed to proceed. 

Before an integer variable can be used as an argument to any of the other barrier routines, it must first 
be identified as a barrier variable by BARASGN. 

IMPLEMENTATION 

This routine is available both to users of the COS and UNICOS operating systems. 
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NAME 

BARREL - Releases the identifier assigned to a barrier 

SYNOPSIS 

CALL BAKREL(ttame) 

DESCRIPTION 

name Integer variable used as a barrier 

IMPLEMENTATION 

This routine is available both to users of the COS and UNICOS operating systems. 
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NAME 

BARSYNC - Registers the arrival of a task at a barrier 

SYNOPSIS 

CALL BARSYNC(wwk!) 

DESCRIPTION 

name Integer variable used as a barrier 

IMPLEMENTATION 

This routine is available both to users of the COS and UNICOS operating systems. 
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NAME 

BUFDUMP - Unformatted dump of multitasking history trace buffer 

SYNOPSIS 

CALL BUFDUMP(emp/y,rf/i) 

DESCRIPTION 

empty On entry, an integer flag that is 0 if the buffer pointers are to be left unchanged, nonzero if 
the buffer is to be emptied after its contents are dumped 

dn Name of the dataset to which an unformatted dump of the contents of the multitasking his- 

tory trace buffer is to be written. If 0, the dataset passed to BUFTUNE is used; if no 
dataset was specified through BUFTUNE, the request is ignored. 

BUFDUMP writes an unformatted dump of the contents of the multitasking history trace buffer to a 
specified dataset dn can later be used by MTDUMP to examine the dataset and provide formatted 
reports of its contents. Actions are reported in chronological order. A special entry is added if the 
buffer has overflowed and entries have been lost 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

BUFPRINT - Formatted dump of multitasking history trace buffer to a specified dataset 

SYNOPSIS 

CALL BUFPRINT(«np<yW«]) 
DESCRIPTION 

empty On entry, an integer flag that is 0 if the buffer pointers are to be left unchanged or nonzero 
if the buffer is to be emptied after its contents are printed 

dn Name of the dataset or file to which a formatted dump is to be written. If none is specified, 

$OUT (under COS) or stdout (under UNICOS) is used. 

BUFPRINT writes a formatted dump of the contents of the multitasking history trace buffer to a 
specified dataset Actions are reported in chronological order. 

EXAMPLE 

This example of BUFPRINT leaves the buffer unchanged after its output to $OUT: 
IEMPTY = 0 

CALL BUFPRINT(EMPTY) 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

BUFDUMP 
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NAME 

BUFTUNE - Tune parameters controlling multitasking history trace buffer 

SYNOPSIS 

CALL KVVrVNE(keyword t value[ t string]) 

DESCRIPTION 

keyword ASCII string, left-justified, blank-filled (see keywords following) 

value Either an integer or an ASCII string (left-justified, blank-filled), depending on the keyword 

string A 24-character string (left-justified, blank-filled) used only with the keyword INFO 

Valid keywords and their associated functions and meanings are as follows: 

Keyword Description 

DN The value of the DN keyword is the dataset which you specify to receive a dump of 

the multitasking history trace buffer. DN itself directs this dump of the buffer to the 
dataset. If BUFTUNE is called without the DN keyword, the multitasking history 
trace buffer is not dumped to any dataset 

FLUSH The minimum-allowed integer number of unused entries in the multitasking history 
trace buffer. When the number of unused entries falls below this level, the buffer is 
automatically flushed; that is, it is written to the dataset specified by the DN option. 
If DN is specified, the default FLUSH value is 40, 

ACTIONS Value is a 128-elemcnt integer army with a flag for each action that can be recorded 
in the multitasking history trace buffer. If the array element corresponding to a par- 
ticular action is nonzero, that action is recorded; if the array element is 0, the action 
is ignored. The array indexes (action codes) corresponding to each action follow: 

Action Code Action 

1 Start task 

2 Complete task 

3 TSKWATT, no wait 

4 Begin wait for task 

5 Run after wait for task 

6 Test task 

7 Assign lock 

8 Release lock 

9 Set lock 

10 Begin wait to set lock 

1 1 Run after wait for lock 

12 Clear lock 

13 Test lock 
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Action Code Action 
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33 


Begin spin-wait for a logical CPU 


34 


Assign barrier 


35 


Release barrier 


36 


Call BARSYNC, no wait 


37 


Begin wait at barrier 


38 


Run after wait for barrier 


39-64 


Reserved for future use 


65-128 


Reserved for user 




access (see BUFUSER) 



INFO The value for this parameter is the integer user action code (65 through 128). 

string is a 24-character information string, unique to each action, that you enter and 
is printed for each user action code that is dumped. 

BUFUSER allows you to add entries to the multitasking history trace buffer. When 
the multitasking history trace buffer is dumped using DEBUG, BUFPRINT, or 
MTDUMP, this 24-character information string is dumped along with each action. 
This information must be available early in the program so that the strings can be 
written to the dump dataset for processing by MTDUMP. The INFO keyword does 
not turn these actions on to be recorded. They are normally on by default, but if 
you have previously turned them off, you may reactivate them using the ACTIONS 
or USERS keyword in a BUFTUNE call. 
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Keyword 



Description 



TASKS 



If value= , ON'H > the actions numbered 1 through 6 are recorded; if value='OFF'H, 
those actions are ignored. The default is 'ON'H. 



LOCKS 



If value='ON'H, the actions numbered 7 through 13 are recorded; if value= , OFF , H ( 
those actions are ignored. The default is 'ON'H. 



EVENTS 



If value= , ON'H, the actions numbered 14 through 21 are recorded; if value= , OFF , H, 
those actions are ignored. The default is 'ON'H. 



CPUS 



If value=*ON'H, the actions numbered 22 through 33 are recorded; if value^'OFF'H, 
those actions are ignored. The default is 'ON'H. 



USERS 



If value^'ON'H, the actions numbered 65 through 128 are recorded; if 
value^'OFF'H, those actions are ignored. The default is value=*ON'H. 



FIOLK If value^ON'H, actions affecting the Fortran I/O lock are recorded; if value=*OFF'H 
they are ignored. Library routines that handle Fortran reads and writes use this lock. 
The default is *OFF»H. 

BUFTUNE can be called any number of times. If it is not called, or before it is called for the first time, 
default parameter values are used. 

Before BUFTUNE is called, all actions involving tasks, locks, events, logical CPUs, and users are 
recorded except for actions involving the Fortran I/O lock, which are ignored. A call to BUFTUNE with 
the TASKS, LOCKS, EVENTS, CPUS, or USERS keyword affects only the actions associated with that 
keyword. The ACTIONS option overrides what has been requested through TASKS, LOCKS, EVENTS, 
CPUS, or USERS. 

EXAMPLES 

The following BUFTUNE examples turn on task actions and turn everything else off: 

* Example #1 
INTEGER ACTION (64) 
DATA ACTION(6* 1,58*0) 

CALL BUFTUNE ('DN'L/DMFFILET) 

* Example #2 

CALL BUFTUNE CDN VDMFHLEX) 
CALL BUFTUNE (TASKSX,'ON'L) 
CALL BUFTUNE (*LOCKS'L/OFFL) 
CALL BUFTUNE ('EVENTS 'L/OFF'L) 
CALL BUFTUNE ('CPUS'L/OFFL) 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

BUFUSER - Adds entries to the multitasking history trace buffer 

SYNOPSIS 

CALL B\JF\JSER(action t data) 

DESCRIPTION 

action On entry, code for the type of action (see action codes in MTDUMP). This value is com- 
pared against the bit of the same number in the mask in global variable G@BUFMSK, set 
up by BUFTUNE. If the mask bit is set, an entry is added to the buffer. This value 
becomes the third word of the buffer entry. 

data Values added to the multitasking history trace buffer in addition to the internal task 
identifier and the current time. These actions-dependent data codes can be user-defined task 
values, a logical CPU number, a lock or event address, or the task identifier of the waited- 
upon task. The only restriction on these values is that they should be a single word. If an 
entry is added to the buffer, this value becomes the fourth word of the entry. 

These entries are added unconditionally. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

EVASGN - Identifies an integer variable to be used as an event 

SYNOPSIS 

CALL E\ASGH(name[,value]) 

DESCRIPTION 

name Name of an integer variable to be used as an event The library stores an identifier into this 
variable; you should not modify this variable. 

value The initial integer value of the event variable. An identifier should be stored into the vari- 
able only if it contains the value. If value is not specified, an identifier is stored into the 
variable unconditionally. 

Before an integer variable can be used as an argument to any of the other event routines, it must first 
be identified as an event variable by EVASGN. 

EXAMPLE 



PROGRAM MULTI 
INTEGER EVSTART.EVDONE 
COMMON /EVENTS/ EVSTART.EVDONE 

C 

CALL EVASGN (EVSTART) 
CALL EVASGN (EVDONE) 

C 

END 

SUBROUTINE SUB 1 
INTEGER EVENT1 
COMMON /E VENT1/ EVENT1 
DATA EVENT1 /-l/ 

C 

CALL EVASGN (EVENTl.-l) 

C 

END 



IMPLEMENTATION 

This routine is available to users of both the COS and UN1COS operating systems. 
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NAME 

EVCLEAR - Clears an event and returns control to the calling task 

SYNOPSIS 

CALL EVCLEAR(/i<otw) 

DESCRIPTION 

name Name of an integer variable used as an event 

EVCLEAR clears an event and returns control to the calling task. When the posting of a single event is 
required (a simple signal), EVCLEAR should be called immediately after EVWAIT to note that the post- 
ing of the event has been detected. 

EXAMPLE 

PROGRAM MULTI 
INTEGER EVSTART.EVDONE 
COMMON/EVENTS/ EVSTART.EVDONE 

C 

CALL EVASGN (EVSTART) 
CALL EVASGN (EVDONE) 

C 

CALL EVPOST (EVSTART) 
END 

SUBROUTINE MULTI2 
INTEGER EVSTART.EVDONE 
COMMON /EVENTS/ EVSTART.E VDONE 

C 

CALL EVWAIT (EVSTART) 
CALL EVCLEAR (EVSTART) 

C 

END 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

EVPOST - Posts an event and returns control to the calling task 

SYNOPSIS 

CALL EVPOST(«ime) 

DESCRIPTION 

name Name of an integer variable used as an event 

EVPOST posts an event and returns control to the calling task. Posting the event allows any other tasks 
waiting on that event to resume execution, but this is transparent to the task calling EVPOST. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

EVREL - Releases the identifier assigned to the task 

SYNOPSIS 

CALL EVREUname) 

DESCRIPTION 

name Name of an integer variable used as an event 

If tasks are currently waiting for this event to be posted, an error results. This subroutine detects 
erroneous uses of the event beyond the specified region. The event variable can be reused following 
another call to EVASGN. 

EXAMPLE 



PROGRAM MULTI 
INTEGER EVSTART,EVDONE 
COMMON /EVENTS/ EVSTARTJEVDONE 

C 

CALL EVASGN (EVSTART) 
CALL EVASGN (EVDONE) 

C 

CALL EVPOST (EVSTART) 

C 

C EVSTART WILL NOT BE USED FROM NOW ON 
CALL EVREL (EVSTART) 

C 

END 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

EVTEST - Tests an event to determine its posted state 

SYNOPSIS 

LOGICAL EVTEST 
return=EVTEST(name) 

DESCRIPTION 

return A logical .TRUE, if the event is posted. A logical the event is not posted. 
name Name of an integer variable used as an event 

NOTE 

EVTEST and return must be declared as type LOGICAL in the calling module. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

EVWAIT - Delays the calling task until the specified event is posted 

SYNOPSIS 

CALL EYWMT(riame) 

DESCRIPTION 

name Name of an integer variable used as an event 

If the event is already posted, the task resumes execution without waiting. 

EXAMPLE 



SUBROUTINE MULTI2 
INTEGER EVSTART.EVDONE 
COMMON /EVENTS/ EVSTART.EVDONE 

C 

CALL EVWAIT (EVSTART) 

C 

END 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

JCCYCL - Returns machine cycle time 

SYNOPSIS 

INTEGER JCCYCL 
integer = JCCYCLO 

DESCRIPTION 

integer Integer representing the cycle time of the machine in picoseconds. 

JCCYCL returns the contents of the Job Control Block (JCB) field JCCYCL. For a CRAY X-MP com- 
puter system with a clock period of 8.5 nanoseconds, JCCYCL returns the integer 8,500. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

LOCKASGN - Identifies an integer variable intended for use as a lock 

SYNOPSIS 

CALL LOCKASGN(name[,value]) 

DESCRIPTION 

name Name of an integer variable to be used as a lock. The library stores an identifier into this 
variable; you should not modify this variable. 

value The initial integer value of the lock variable. An identifier should be stored into the vari- 
able only if it contains the value. If value is not specified, an identifier is stored into the 
variable unconditionally. 

Before an integer variable can be used as an argument to any of the other lock routines, it must first be 
identified as a lock variable by LOCKASGN. 

IMPLEMENTATION 

This routine is available to users of both the COS and UMCOS operating systems. 
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NAME 

LOCKOFF - Clears a lock and returns control to the calling task 

SYNOPSIS 

CALL LOCKOFF(/wmg) 

DESCRIPTION 

name Name of an integer variable used as a lock 

LOCKOFF clears a lock and returns control to the calling task. 

Clearing the lock may allow another task to resume execution, but this is transparent to the task calling 
LOCKOFF. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

LOCKON - Sets a lock and returns control to the calling task 

SYNOPSIS 

CALL LOCKON(/uwu») 

DESCRIPTION 

name Name of an integer variable used as a lock 

LOCKON sets a lock and returns control to the calling task. 

If the lock is already set when LOCKON is called, the task is suspended until the lock is cleared by 
another task and can be set by this one. In either case, the lock will have been set by the task when it 
next resumes execution. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

LOCKREL - Releases the identifier assigned to a lock 

SYNOPSIS 

CALL LOCKREUname) 

DESCRIPTION 

name Name of an integer variable used as a lock 

If the lock is set when LOCKREL is called, an error results. This subroutine detects some errors that 
arise when a task is waiting for a lock that is never cleared. The lock variable can be reused following 
another call to LOCKASGN. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

LOCKTEST - Tests a lock to determine its state flocked G r unlocked) 

SYNOPSIS 

LOGICAL LOCKTEST 
remrn=LOCKTEST(nam<?) 

DESCRIPTION 

return A logical .TRUE, if the lock was originally in the locked state. A logical .FALSE, if the 
lock was originally in the unlocked state, but has now been set 

name Name of an integer variable used as a lock 

Unlike LOCKON, the task does not wait. A task using LOCKTEST must always test the return value 
before continuing. 

NOTE 

LOCKTEST and return must be declared type LOGICAL in the calling module. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

MAXLCPUS - Returns the maximum number of logical CPUs that can be attached at one time to your 
job 

SYNOPSIS 

INTEGER MAXLCPUS 
integer = MAXLCPUSO 

DESCRIPTION 

integer Integer value for the maximum number of CPUs that can be attached at one time to your 
job. 

MAXLCPUS returns the contents of the Job Control Block (JCB) field JCMCP. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

TSECND - Returns elapsed CPU time for a calling task during a multitasked program 

SYNOPSIS 

second=TSECND([result]) 
CALL TSECND(second) 

DESCRIPTION 

second Result; elapsed CPU time (in floating-point seconds) 
result Same as above (optional for function call) 

TSECND returns the elapsed CPU time (in floating-point seconds) of a calling process since the start of 
that process, than subsequent calls due to certain initializations performed by the routine. If the cost of 
calling TSECND is important, ignore the initial call when computing TSECND's time. 

EXAMPLE 

The following example calculates how much of the total execution time for a multitasked program is 
accumulated by the calling process. 

BEFORE = SECONDO 
TBEFORE = TSECNDO 

CALL DOWORKO ! The subroutine DOWORK or 

AFTER = SECONDO ! something it calls may be 

TAFTER = TSECND() ! multitasked. 

CPU = (AFTER - BEFORE) 
TCPU = (TAFTER - TBEFORE) 
MYPORTION = TCPU/CPU 

IMPLEMENTATION 

This routine is available only to users of the UNICOS operating system. 

SEE ALSO 

SECOND(3U) 
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NAME 



TSKSTART - Initiates a task 



SYNOPSIS 

CALL TSKSTA.RT(task-arrayjiamellist]) 
DESCRIPTION 



task-array 



name 



list 



Task control array used for this task. Word 1 must be set. Word 3, if used, must also be 
set. On return, word 2 is set to a unique task identifier that the program must not 
change. 

External entry point at which task execution begins. Declare this name EXTERNAL in 
the program or subroutine making the call to TSKSTART. (Fortran does not allow a pro- 
gram unit to use its own name in this parameter.) 

List of arguments being passed to the new task when it is entered. This list can be of 
any length. See the CRAY Y-MP. CRAY X-MP EA, and CRAY X-MP Multitasking 
Programmer's Manual, publication SR-0222, for restrictions on arguments included in list 
(optional parameter). 



EXAMPLE 



C 
C 
C 
C 
C 
C 



C 
C 
C 



C 
C 



PROGRAM MULTI 

INTEGER TASK1ARY(3).TASK2ARY(3) 
EXTERNAL PLLEL 
REAL DATA(40000) 

LOAD DATA ARRAY FROM SOME OUTSIDE SOURCE 



CREATE TASK TO EXECUTE FIRST HALF OF THE DATA 

TASK1ARY(1)=3 
TASK1ARY(3)=TASK r 

CALLTSKSTART(TASK1ARY,PLLEL,DATA(1),20000) 

CREATE TASK TO EXECUTE SECOND HALF OF THE DATA 

TASK2ARY(1)=3 
TASK2ARY(3)=TASK T 

CALL TSKSTART(TASK2ARY,FLLEL,DATA(20001),20000) 
END 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

TSKTEST - Returns a value indicating whether the indicated task exists 

SYNOPSIS 

LOGICAL TSKTEST 

return=TSKTES>T(task-array) 

DESCRIPTION 

return A logical .TRUE, if the indicated task exists. A logical .FALSE, if the task was never 

created or has completed execution. 

task-array Task control array TSKTEST and return must be declared type LOGICAL in the calling 
module. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

TSKTUNE - Modifies tuning parameters within the library scheduler 
SYNOPSIS 

CALL TSKTVNE(keyword u value i Jceyword 2 , value 2 ,».) 
DESCRIPTION 

Each keyword is a Fortran constant or variable of type CHARACTER. Each value is an integer. The 
parameters must be specified in pairs, but the pairs can occur in any order. Legal keywords are as fol- 
lows: 

Keyword Description 

MAXCPU Maximum number of COS logical CPUs allowed for the job 

DBRELEAS Deadband for release of logical CPUs 

DBACTIVE Deadband for activation or acquisition of logical CPU 

HOLDTIME Number of clock periods to hold a CPU, waiting for tasks to become ready, before 
releasing it to the operating system 

SAMPLE Number of clock periods between checks of the ready queue 

Each parameter has a default setting within the library and can be modified at any time to another valid 
setting. 

For more information about using this routine, see the CRAY Y-MP, CRAY X-MP EA, and CRAY X-MP 
Multitasking Programmer's Manual, publication SR-0222. 

NOTE 

This routine should not be used when multitasking on a CRAY-1 computer system. Because of variabil- 
ity between and during runs, the effects of this routine are not reliably measurable in a batch environ- 
ment 

EXAMPLE 

CALL TSKTUNECDBACnVEM/MAXCPU',2) 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

TSKVALUE - Retrieves user identifier specified in task control array 

SYNOPSIS 

CALL TSKVALUE<retarn) 

DESCRIPTION 

return Integer value that was in word 3 of the task control array when the calling task was created. 

A 0 is returned if the task control array length is less than 3 or if the task is the initial task. 

TSKVALUE retrieves the user identifier (if any) specified in the task control array used to create the 
executing task. 

EXAMPLE 



SUBROUTINE PLLEL(DATA,SIZE) 
REAL DATA(SIZE) 

C 

C DETERMINE WHICH OUTPUT FILE TO USE 
C 

CALL TSKVALUE(IVALUE) 
IF(IVALUE .EQ. 'TASK l')THEN 

IUNITNO=3 
ELSEIF(IVALUE .EQ. , TASK2 , )THEN 

IUNITNO=4 
ELSE 

STOP !Error condition; do not continue. 
ENDIF 

C 

END 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

TSKWAIT - Waits for the indicated task to complete execution 

SYNOPSIS 

CALL TSKWAJT(task-array) 

DESCRIPTION 

task-array Task control array 

EXAMPLE 



PROGRAM MULTI 

INTEGER TASK1 ARY(3),TASK2ARY(3) 
EXTERNAL PLLEL 
REAL DATA(40000) 

C 

C LOAD DATA ARRAY FROM SOME OUTSIDE SOURCE 

C 

C 

C CREATE TASK TO EXECUTE FIRST HALF OF THE DATA 
C 

TASK1ARY(1)=3 
TASK1ARY(3)=TASK 1' 

C 

CALL TSKSTART(TASK1ARYJ>IXEL,DATA(1)£0000) 

C 

C CREATE TASK TO EXECUTE SECOND HALF OF THE DATA 
C 

TASK2ARY(1)=3 

T AS K2 AR Y(3)=*T AS K T 

C 

CALLTSKSTART(TASK2ARY,PLLEL,DATA(20001),20000) 

C 

C NOW WAIT FOR BOTH TO FINISH 
C 

CALL TSKWAIT(TASK1 ARY) 
CALL TSKWAIT(TASK2ARY) 

C 

C AND PERFORM SOME POST-EXECUTION CLEANUP 

C 

C 

END 

In the preceding example, TSKSTART is called once for each of two tasks. As an alternative, the second 
TSKSTART could be replaced by a call to PLLEL, and the TSKWAIT removed. This alternate approach 
reduces the overhead of the additional task but can make understanding the program structure more difficult. 
The two approaches, however, produce the same results. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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15. TIMING ROUTINES 



The timing routines are grouped as follows: 

• Time stamp routines 

• Time and date routines 

TIME STAMP ROUTINES 

System accounting programs use these routines to convert between various representations of time. 
Time stamps can be used to measure from one point in time to another. Cray time stamps are defined 
relative to an initial date of January 1, 1973. 

The following table contains the purpose, name, and entry for each time stamp routine. 



Time stamp Routines 


Purpose 


Name 


Entry 


Convert from date and time to 
time stamp 


DTTS 


DTTS 


Convert time stamps into ASCII date 
and time strings 


TSDT 


TSDT 


Convert time stamp to real-time clock 
value 


TSMT 


TSMT 


Convert real-time clock value to 
time stamp 


MTTS 


Return time stamp units in standard 
time units 


UNITTS 


UNITTS 



TIME AND DATE ROUTINES 

Time and date routines produce the time and/or date in specified forms. These routines can be called as 
Fortran functions or routines. AU of the routines are called by address. 

The following table contains the purpose, name, and entry for each time and date routine. 
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Time and Date Routines 


Purpose 


Name 


Heading 


Return the current system clock time 


CLOCK 


CLOCK 


Return the current date 


DATE 


DATE 


Return the current Julian date 


JDATE 


Return real-time clock values 


RTC 
IRTC 


RTC 


Return the elapsed CPU time (in 
floating-point seconds) since the 
start of a job 


SECOND 


SECOND 


Return the elapsed wall-clock time 
since the initial call to TIM EF 


TIMEF 


TIMEF 


Return the CPU time (in floating- 
point seconds) remaining for a job 


TREMAIN 


TREMAIN 
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NAME 

CLOCK - Returns the current system-clock time 

SYNOPSIS 

<wtt?=CLOCK( ) 
CALL CLOCK(rfwc) 

DESCRIPTION 

time Time in hh:mm:ss format (type integer) 

CLOCK returns the current system-clock time in ASCII hh:mm:ss format. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

DATE, JDATE - Returns the current date and the current Julian date 

SYNOPSIS 

rfate=DATEO 
CALL DATE(date) 

<fate=JDATEO 
CALL JDATE(<to/<0 

DESCRIPTION 

date For DATE, today's date in mmjddlyy format (type integer). For JDATE, today's Julian date 
in yyddd format. 

DATE returns today's date in mmlddfyy format. 

JDATE returns today's Julian (ordinal) date in yyddd format, left-justified, blank-filled. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

DTTS - Converts ASCII date and time to time-stamp 

SYNOPSIS 

ts=DTTS(date .time.ts) 

DESCRIPTION 

ts Time stamp corresponding to date and time (type integer). On return, if ts=O t an incorrect 

parameter was passed to DTTS. 

date On entry, ASCII date in mmfdd/yy format 

time On entry, ASCH time in hh:mm:ss format 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

RTC, IRTC - Return real-time clock values 

SYNOPSIS 

time=RTC( ) 
CALL RTC(rime) 

time=1RTC( ) 
CALL IRTC(ftme) 

DESCRIPTION 

time For RTC, the low-order 46 bits of the clock register expressed as a floating-point integer 
(real type). For IRTC, the current clock register content expressed as an integer. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

SECOND - Returns elapsed CPU time 

SYNOPSIS 

second=SECOND([result]) 
CALL SECOND(second) 

DESCRIPTION 

second Result; CPU time (in floating-point seconds) accumulated by all processes in a program. 
result Same as above (optional for function call) 

SECOND returns the elapsed CPU time (in floating-point seconds) since the start of a program, including 
time accumulated by all processes in a multitasking program. 

Under COS, all programs run as job steps of a job, and SECOND returns the total execution time for all 
job steps since the job started. Under UNICOS, SECOND returns execution time for the current pro- 
gram. For example, a job (COS or UNICOS) runs a 50-second program 10 times. In COS, if you make 
a SECOND call at the end of the 10th run, SECOND will return 500 seconds. In UNICOS, a SECOND 
call at the end of the 10th run (or first or third or seventh) will return 50 seconds. 

NOTE 

The initial call to SECOND may take longer than subsequent calls due to certain initializations per- 
formed by the routine. If the cost of calling SECOND is important, ignore the initial call when comput- 
ing SECOND'S time. The assignment to JUNK in the second example below serves this purpose. 

EXAMPLE 

BEFORE = SECONDO 
CALL DOWORKO 
AFTER = SECONDO 
CPUTDME = AFTER - BEFORE 

This example calculates the CPU time used in DOWORK. If the CPU time is small enough that the 
overhead for calling SECOND may be significant, the following example is more accurate: 

JUNK = SECONDO 
TO = SECONDO 
OVERHEAD = SECONDO - TO 
BEFORE = SECONDO 
CALL DOWORKO 
AFTER = SECONDO 

CPUTTME - (AFTER - BEFORE) - OVERHEAD 

IMPLEMENTATION 

This routine is available to users of both the UNICOS and COS operating systems. 

SEE ALSO 

TSECND(3U) 



SR-0113 



15-7 



D 



TIMEF(3U) 



TIMEF(3U) 



NAME 

TIMEF - Returns elapsed wall-clock time since the call to TIMEF 

SYNOPSIS 

timef=TIMEF([resultJ) 
CALL TIMEF(o"me/) 

DESCRIPTION 

timef Elapsed wall-clock time (in floating-point milliseconds) since the initial call to TIMEF. 
Type real. The initial call to TIMEF returns 0. 

result Same as timef 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

TREMAIN - Returns the CPU time (in floating-point seconds) remaining for job 

SYNOPSIS 

CALL TREMAIN(r««/0 

DESCRIPTION 

result Calculated CPU time remaining; stored in result. Type real. 

NOTE 

The time remaining is the time specified on the COS JOB statement, minus the time elapsed so far. 

The value returned by TREMAIN may not always be updated between calls. For instance, the values 
for X and Y may be the same in the following code: 

CALL TREMAIN(X) 
DO 101= 1, 1000000 
10 T(I) = FLOAT(I) 
CALL TREMAIN(Y) 

The value that TREMAIN uses is only updated when a program is exchanged out of memory. If calls 
to TREMAIN occur during the same time slice (that is, the job has not been exchanged), the values will 
be the same. If more accurate times are required, use the routine SECOND and subtract the value 
from your job's time limit 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

TSDT - Converts time-stamps to ASCII date and time strings 

SYNOPSIS 

CALL TSDT(ts t date f hhmmss,ssss) 

DESCRIPTION 

ts Time-stamp on entry (type integer) 

date Word to receive ASCII date in mm/ddfyy format 

hhmmss Word to receive ASCII time in hh:mm:ss format 

ssss Word to receive ASCII fractional seconds in ssssnnn format 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

TSMT, MTTS - Converts time-stamp to a corresponding real-time value, and vice versa 

SYNOPSIS 

irte=TSMT(w[ f q)type,cpcycle]) 
tssMTT$(irtc{ f cptype,cpcycle]) 

DESCRIPTION 

irtc For TSMT, real-time clock value corresponding to specified time-stamp. For MTTS, real- 

time clock value to be converted. 

ts For TSMT, time-stamp to be converted (type integer). For MTTS, time-stamp correspond- 

ing to real-time clock value (type integer). 

cptype CPU type. This is an optional argument specifying the CPU type. Valid values are as fol- 
lows: 

1 CRAY-1, models A and B 

2 CRAY-1, model S 

3 CRAYX-MP 

4 CRAY-1, model M 

The default is the CPU of the host machine. The cptype is necessary when doing a conver- 
sion for a machine type other than the host machine. The real-time clock value is different 
on, for instance, a CRAY X-MP computer system than on a CRAY-1 computer system 
because of the difference in cycle time. For TSMT to generate a correct result and for 
MTTS to correctly interpret its argument, they must know the correct machine type. 

cpcycle CPU cycle time in picoseconds; for instance, a CRAY X-MP computer system with a cycle 
time of 8.5 nanoseconds would be specified as 8500. The default is the cycle time of the 
host machine. 

TSMT converts a time-stamp to a corresponding real-time value. MTTS converts a real-time clock value 
to its corresponding time-stamp. 

IMPLEMENTATION 

These routines are available only to users of the COS operating system. 
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NAME 

UNTTTS - Returns time-stamp units in specified standard time units 

SYNOPSIS 

ts=\JNTTTS(periods,units) 

DESCRIPTION 

ts Number of time-stamp units in periods and units (type integer) 

periods Number of time-stamp units to be returned in standard time units (that is, number of 
seconds, minutes, and so on); type integer. 

units Specification for the units in which periods is expressed. The following values are 
accepted: DAYS'H, 'HOURS'H, 'MINUTES'H, 'SECONDS*!!, 'MSEC'H (milliseconds), 
TJSEC'H (microseconds), 'USECIOO'H (100s of microseconds). Left-justified, blank-filled, 
Hollerith. UNTTTS must be declared type integer. 

EXAMPLE 

/^UNITTS(2, , DAYS t H) 

ts Number of time-stamp units in 2 days 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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16. PROGRAMMING AID ROUTINES 



Programming aids consist of the following types of routines: 

• Flowtrace routines 

• Traceback routines 

• Dump routines 

• Exchange Package processing routines 

• Hardware performance monitor interface routine 

FLOWTRACE ROUTINES 

Flowtrace routines process the CFT flowtrace option (ON=F). The Cray Fortran compiler automatically 
inserts calls to these routines (see the Fortran (CFT) Reference Manual, or the CFT77 Reference Manual 
for details on flowtracing). Flowtrace routines are called by address. For more information on flow 
trace calls from CAL, see the System Library Reference Manual, publication SM-0114, the UNICOS Per- 
formance Utilities Reference Manual, publication SR-2040, and the COS Performance Utilities Reference 
Manual, publication SR-0146. 

NOTE 

Many of the flowtrace subroutines begin with the characters "FLOW0\ You should avoid using names 
with this prefix. 

The following table contains the purpose, name, and call to each flow trace routine. 



Flowtrace Routines 


Purpose 


Name and Call 


Process entry to a subroutine 


CALL FLOWENTR 


Process RETURN execution 


CALL FLOWEXIT 


Process a STOP statement 


CALL FLOWSTOP 


Initiate a detailed tracing of 
every call and return 


SETPLIMQ(/irt£5) 

lines Number of lines to be 
printed (one for each call 
and return). If lines 
is < 0, no lines are printed, 
or printing is terminated. 


Print the final report 


CALL FLOWOSTPfcufdev) 

outdev Device to which 
the report is written 


Return name of the caller 


SUBROUTINE GETNAMEQ(/iawe) 
INTEGER name 


Return the cycles charged to a job 


mfeger=IGETSEC( ) 


Return the cycle time in picoseconds 
(value of field JCCYCL in the JCB) 


integer=JCCYCL( ) 
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TRACEBACK ROUTINES 

The traceback routines list all subroutines active in the current calling sequence (TRBK) and return 
information for the current level of the calling sequence (TRBKLVL). Traceback routines return 
unpredictable results when subroutine linkage does not use CRT standard calling sequences. 



DUMP ROUTINES 

Dump routines produce a memory image and are called by address. 

The following table contains the purpose, name, and entry of each dump routine* 



Dump Routines 


Purpose 


Name 


Entry 


Print a memory dump to a dataset 


CRAYDUMP 


CRAYDUMP 


Dump memory to $OUT and abort the job 


DUMP 


DUMP 


Dump memory to $OUT and return control 
to the calling program 


PDUMP 


Create an unblocked dataset 
containing the user job area image 


DUMPJOB 


DUMPJOB 


Copy current register contents 
to$OUT 


SNAP 


SNAP 


Produce a symbolic dump 


SYMDEBUG 


SYMDEBUG 


Produce a snapshot dump of a 
running program 


SYMDUMP 


SYMDUMP 



EXCHANGE PACKAGE PROCESSING ROUTINES 

Exchange Package processing routines (XPFMT and FXP) switch execution from one program to 
another. An Exchange Package is a 16-word block of memory associated with a particular program. 

HARDWARE PERFORMANCE MONITOR INTERFACE ROUTINE 

PERF provides an interface to the hardware performance monitor feature on CRAY X-MP computer sys- 
tems. 
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NAME 

CRAYDUMP - Prints a memory dump to a specified dataset 

SYNOPSIS 

CALL CRAYDlMPtfwaJwaMn) 

DESCRIPTION 

fwa First word to be dumped 

Iwa Last word to be dumped 

dn Name or unit number of the dataset to receive the dump output 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

DUMP, PDUMP - Dumps memory to $OUT and cither abort or return to the calling program 

SYNOPSIS 

CALL DUMP(jwaJwa,type) 
CALL PDUMPywa t twa f type) 

DESCRIPTION 

fwa First word to be dumped 

Iwa Last word to be dumped 

type Dump type code, as follows: 

0 or 3 Octal dump 

1 Floating-point dump 

2 Integer dump 

DUMP dumps memory to $OUT and aborts the job. PDUMP dumps memory to $OUT and returns con- 
trol to the calling program. 

NOTES 

If 4 is added to the dump type code, the first word and last word addresses specified are then addresses 
of addresses (indirect addressing). 

First word/last word/dump type address sets can be repeated up to 19 times. 

IMPLEMENTATION 

These routines are available only to users of the COS operating system. 
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NAME 

DUMPJOB - Creates an unblocked dataset containing the user job area image 

SYNOPSIS 

CALL DUMPJOB(rfn) 

DESCRIPTION 

dn Fortran unit number or Hollerith unit name. If no parameter is supplied, $DUMP is used by 

default. 

DUMPJOB creates an unblocked dataset containing the user job area image, including register states and 
the Job Table Area. This data is suitable for input to the DUMP or DEBUG programs. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

DUMP, SYMDEBUG 



SR-0113 



16-5 



D 



FXP(3COS) 



FXP(3COS) 



NAME 

FXP - Formats and writes the contents of the Exchange Package to an output dataset 

SYNOPSIS 

CALL FXP(dsppcp t vm,ret) 

DESCRIPTION 

dsp Output Dataset Parameter Table address 

xp Exchange Package address 

vm Vector mask (VM) to be formatted 

ret Contents of BO register to be formatted 

FXP formats and writes to the output dataset the contents of the Exchange Package, the contents of the 
vector mask (VM), and the contents of the BO register. This routine complements the user reprieve pro- 
cessing. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

GETNAMEQ - Returns name of the caller 

SYNOPSIS 

SUBROUTINE GETNAMEQ(/ia»ie) 
INTEGER name 

DESCRIPTION 

GETNAMEQ returns the name of the caller of its caller. 

Suppose FOO calls BAR. If BAR calls GETNAMEQ, name is set to "FOO". (The result is left-justified 
in a Cray word.) 

NOTES 

GETNAMEQ returns only the first 8 characters of a name. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

IGETSEC - Returns the cycles charged to a job 

SYNOPSIS 

Call from Fortran: 

integer=IGETSEC( ) 
DESCRIPTION 

integer Cycles charged to a job 

IGETSEC returns the cycles charged to a job up to its own execution. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

PERF - Provides an interface to the hardware performance monitor feature on the CRAY X-MP main- 
frame 



SYNOPSIS 

CALL PEKF(fmc t group l buffer t buf7) 

DESCRIPTION 



func Performance monitor function. Either an integer function number or one of the following 

ASCII strings, left-justified, and zero-filled, 

'ON'L Enable performance monitoring 

'OFF'L Disable performance monitoring 

"REPORTL Report current performance monitor statistics 
KESET'L Report current statistics, then clear performance 
monitor tables 

group Performance monitor group number (type integer). See the Performance Counter Group 
Description table for group numbers and their coiresponding counters and counter contents. 

buffer First word address of a performance monitor request buffer 

bufl Number of words in the buffer array 



Thirty-two counters are available, arranged into four groups of eight counters each. Only one group 
can be accessed at a time. 

The PERF request block format contains a fixed header and a variable number of subblocks following 
the header. The first 3 words of the header are set in subroutine PERF before calling the system, while 
the remaining words in the header are returned by the system. 

The words in the block header allow you to analyze the information returned in the subblocks without 
the use of constants. This allows programs to continue executing correctly when the contents of the 
header or the subblocks change. 
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The block header format is as follows: 



HMRSF 

HMRGN 

HMRNW 

HMRNU 

HMRBH 

HMRTS 

HMRCT 

HMRCP 

HMRGE 

HMRNC 

HMRNG 

HMRLE 



Field 



Word 



0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 



Description 

Subfunction (0 through 3) 

Group number (0 through 3) for PMSON 

Length of the request block 

Number of words used 

Number of words in the block header 

Set to nonzero if the block is too small 

Offset to the first group counter in the subblock 

Offset to the first group accounted CPU cycles 

Length of the counter group entry in subblock 

Number of counters in each group entry 

Number of groups in each subblock 

Length of subblock entries 



Timing subblocks are returned for every REPORT and RESET call. Each subblock contains hardware 
performance monitor data from a single COS user task. 

The address of the first timing subblock is at (BLOCK FWA) + (contents of block header field HMRBH), 
with the next following (contents of block header field HMRLE) word after the first. Subblocks end 
when the offset to the next block would start after (contents of block header field HMRNU) words. 

Each subblock contains a 2-word header, with fields HMTN and HMGRP. HMTN is the COS user task 
number associated with the subblock. HMGRP is the last hardware performance monitor group number 
active for the subblock. 

Within the subblock, there are (contents of block header field HMRNG) performance monitor groups 
reported. Each group report consists of two fields: counters associated with the group, and the number 
of CPU cycles that were accounted for while the specified monitor was active. The offset to the first 
group counter is (contents of block header field HMRCT) words into the subblock; there are (contents 
of block header field HMRNC) counters for each performance monitor group. The offset to the first 
group's accounted CPU cycle is at (contents of block header field HMRCP). 

Timing groups within a subblock follow each other by (contents of block header field HMRGE) words, 
The subblock format follows: 



Field 


Word 


Description 


HMTN 


0 


User task number 


HMGRP 


1 


Latest performance monitor group number 


HMCNTO 


2-9 


Group 0, counter 0 through 7 


HMCCYO 


10 


Group 0, accounted CPU cycles 


HMCNT1 


11-18 


Group 1, counter 0 through 7 


HMCCY1 


19 


Group 1, accounted CPU cycles 


HMCNT2 


20-27 


Group 2, counter 0 through 7 


HMCCY2 


28 


Group 2, accounted CPU cycles 


HMCNT3 


29-36 


Group 3, counter 0 through 7 


HMCCY3 


37 


Group 3, accounted CPU cycles 
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The performance counter group descriptions are listed below 
in the following table. 



Performance Counter Group Descriptions 




r enonii ance 




firoun 


CYh inter 


T}fcscrintinn 






JNumoer oi. 




A 
U 


Instructions issued 




1 
I 


l,iock penous noiaing issue 




z 


reicnes 


u 


5 


I/O references 




A 
H 


\*r\j reierences 




C 

3 


Floating-point add operations 




6 


PlfMiHn0'-fV>int tniilttntv nrw^r a t i c\r\ <i 




7 

> 


T*Inatin<T-rv*inf fwinnvsil rwv^witinnc 






Hold issue conditions: 




0 


Semaphores 




1 


Shared registers 




2 


A registers and functional units 


1 

1 


3 


S registers and functional units 




4 


V registers 






V functional units 




u 


00 dial IJICillUIj 




7 








Number of: 




n 
U 


Fetches 




1 


Scalar references 




Z 


Scalar conflicts 


z> 




ieicrences 






lfvj conn ic is 




< 

J 


dhxjc references 




6 


Block conflicts 




7 


Vector memory references 






Number of: 




0 


000 - 017 instructions 




1 


020 - 137 instructions 




2 


140 ~ 157, 175 instructions 


3 


3 


160 - 174 instructions 




4 


176» 177 instructions 




5 


Vector integer operations 




6 


Vector floating-point operations 




7 


Vector memory references 



IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

SETPLEVfQ - Initiates detailed tracing of every call and return 

SYNOPSIS 

Call from CAL and Fortran: 

CALL SETPLIMQ(/«m) 
DESCRIPTION 

lines Number of lines to be printed (one for each call and return). If lines <, 0, no lines are 

printed, or printing is terminated. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

SNAP - Copies current register contents to $OUT 

SYNOPSIS 

CALL SNAP(r<?£? control form) 

DESCRIPTION 

regs Code indicating registers to be copied, as follows: 

1 B registers 

2 T registers 

3 B and T registers 

4 V registers 

5 B and V registers 

6 T and V registers 

7 B, T, and V registers 

control Control word (currently unused) 

form Code indicating the format of the dump. Dumps from registers S, T, and V are controlled 
by the following type codes: 

0 Octal 

1 Floating-point 

2 Decimal 

3 Hexadecimal 

Dumps from registers A and B are in octal format 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

SYMDEBUG - Produces a symbolic dump 

SYNOPSIS 

CALL SYMDEBUGCparamljaram}:) 

DESCRIPTION 

param SYMDEBUG parameters, param must be in uppercase. 

Some SYMDEBUG parameters allow you to specify a value along with the parameter. In these cases, 
param=value substitutes for param. 

SYMDEBUG uses the following parameters: 

S-sdn sdn names the dataset or file containing the debug symbol tables. The default is $DEBUG. 
The symbol file is SYMBOLS. 

L=ldn Idn names the dataset or file to receive the listing output from the symbolic debug routine. 
The default is $OUT. 

CALLS=n Number of routine levels to be looked at in a symbolic dump. For each task reported, 
SYMDEBUG traces back through the active subprograms the number of levels specified by 
n. Routines for which no symbol table information is available are not counted for pur- 
poses of the CALLS count If this parameter is omitted, or if CALLS is specified without a 
value, the default is 50. 

MAXDIM=*#m ( :dim]JR 

Maximum number of elements from each dimension of the arrays to be dumped. MAXDIM 
allows you to sample the contents of arrays without creating huge amounts of output 
When MAXDIM is specified, arrays are dumped in storage order (row, column for Pascal; 
column, row for Fortran), MAXDIM applies to all blocks dumped. The default is MAX- 
DIM=20:5:2:1:1:1:1. No more than seven dimensions can be specified, 

BLOCKS=Mfc(;Mfc} 

List of common blocks to be included from the symbolic dump. A maximum of 20 blocks 
can be specified. Separate the blks with colons. All symbols (qualified by the SYMS and 
NOTSYMS parameters) in the named blocks are dumped. Default is no common blocks 
dumped; if you specify BLOCKS without any blks, all common blocks declared in routines 
to be dumped are included in the symbolic dump. 

NOTBLKS=nW*{;nW*} 

List of common blocks to be excluded in the symbolic dump. A maximum of 20 blocks 
can be specified. Separate the nblks with colons. This parameter is used in conjunction 
with BLOCKS and takes precedence over the BLOCKS parameter. 

RPTBLKS Repeat blocks; when this option is used, the contents of common blocks specified with the 
BLOCKS and NOTBLKS parameters are displayed for each subroutine in which they are 
declared. The default displays common blocks only once. 

PAGES=np Page limit for the symbolic dump routine. Every page is worth 45 lines of output from 
SYMDEBUG, The default np is 70. 
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EXAMPLE 

The following are example calls from Fortran to S YMDEBUG: 
CALL SYMDEBUG('CALLS=40,RPTBLKS.') 
CALL SYMDEBUG( , BLOCKS=AA:BB;CC. , ) 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 

SEE ALSO 

The UNICOS Symbolic Debugging Package Reference Manual, publication SR-0112 
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NAME 

SYMDUMP - Produces a snapshot dump of a running program 
SYNOPSIS 

CALL SYMDUMP (*-b blklist -B -c calls -d dimlist A Ifile -r -s symfile -V -y symlist -Y% 
abort Jlag) 

DESCRIPTION 

SYMDUMP is a library routine that produces the same sort of output as DEBUG. It accepts C character 
descriptors, Fortran hollerith strings, and Pascal packed character arrays. 

The method of calling library routines differs from language processor to language processor, but SYM- 
DUMP accepts the same arguments regardless of the language processor. The argument string, if pro- 
vided, must be enclosed in parentheses, and the options (excluding the abort flag) must be enclosed in 
quotation marks. When calling SYMDUMP from Fortran or Pascal, the quotation marks must be single; 
when calling from C, the quotation marks must be double. All arguments are optional. 

The options indicate the type and extent of information to be dumped by SYMDUMP. The options 
string is passed to SYMDUMP in one of the following forms: 

• As a character descriptor, produced by Fortran and C for defined characters strings 

• As an address of a null terminated string, such as an integer, Hollerith, or Pascal packed char- 
acter array 

The argument string can contain a maximum of 4,096 characters. All options are optional, and they 
may appear in any order. 

Unlike command lines, SYMDUMP option-arguments may not be grouped after one hyphen on the 
SYMDUMP call. That is, SYMDUMPO-V -r f ) is permitted, but SYMDUMPO-Vr') is not permitted. 
The following are valid options and arguments: 

-b blklist 

-B These options control the displaying of common block symbols. The symbols to be 

displayed from any particular common block will depend upon the use of the -Y and -y 
symlist options. 

If neither option is specified, no common blocks are included in the symbolic dump. This 
is the default. If -B is specified, all common blocks are included in the symbolic dump. If 
-b blklist is specified, only the common blocks named in blklist are included in the sym- 
bolic dump. If both options are specified, all common blocks are included in the symbolic 
dump except those in blklisL 

blklist may have up to 20 common blocks named. There is no limit on the length of a 
common block name. The common blocks named in blklist must be separated by commas 
(for example: -b c,d). 

Enter the common blocks named in blklist in the case in which they appear in the symbol 
table. Names may not always appear in the symbol table in the same way they appear in 
your program. The UNICOS Symbolic Debugging Package Reference Manual, publication 
SR-0U2, describes how symbol names appear in the symbol table. 
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calls is an integer that specifies the number of routine levels to be displayed in the sym- 
bolic dump. For each task reported, SYMDUMP traces back through active routines the 
number of levels specified by calls. Routines for which no symbol table information is 
available are not counted for puiposes of the routine level count The default is 50. 

dimlist is an integer that specifies the maximum number of elements from each dimension 
of the arrays to be dumped. SYMDUMP can dump array elements from up to seven dimen- 
sions. The dimensions must be specified by integer values, and the values must be 
separated by commas (example: -d 4,6) 

This option allows you to sample the contents of an array without creating huge amounts of output 
dimlist applies to all blocks dumped, and the arrays are dumped in storage order. The default is *d 

-I Ifile Ifile names an output file. Specifying A file directs SYMDUMP to write output to the specified 
file. If you call SYMDUMP more than once, and you specify -I with the same file each time, 
SYMDUMP output will be appended to the file each time. By default SYMDUMP output is 
written to stdout 

•r Repeat blocks. When this option is used, SYMDUMP displays the contents of common blocks 
specified with the -B and -b blklist for each subroutine in which they are declared. The default 
displays common blocks only once. 

-s symfile 

symfile names a file containing the Debug symbol tables. There is no limit on the length of the 
symfile file name, and it may include a pathname to the desired file. SEGLDR puts both the 
symbol table information and the executable binary in the same file. By default Debug sym- 
bol tables are written to a.out 

•V With -V specified, SYMDUMP generates SYMDUMP release statistics. 

-y symlist 

-Y These options may occur anywhere in the option string in any order. Use one of the following 
methods to control the way symbols arc displayed: 

If neither option is specified, all symbols are displayed. Default 

If only the -Y option is specified, no symbols are displayed. 

If only the -y option is specified, all symbols except those named in symlist are displayed. 

If both options are specified, only the symbols named in symlist are displayed. 

symlist may contain up to 20 named symbols, and there is no limit to the length of the symbol 
names. The symbols named in symlist must be separated by commas (example: -y a, b) 

Enter the symbols in the same case in which they appear in the symbol table. Names may not 
always appear in the symbol table in the same way they appear in your program. 

abort Jlag 

An optional abort Jlag indicates to SYMDUMP whether or not to abort if it finds an error when 
parsing the SYMDUMP statement. An abort Jlag with a value of zero indicates no abort; an 
abort Jag with a value other than zero indicates abort 

You cannot enter an abort Jag if you have not entered any options. 

By default, SYMDUMP examines all options, reports errors found, and generates a dump based 
on the options it could understand; the program does not abort 
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Note that the abort Jlag is not allowed when options contains a Pascal variant array. 

NOTES 

Use SEGLDR or Id(l) to load programs that call SYMDUMP. When using SEGLDR, specify library 
libdb*a, which contains SYMDUMP, on the -1 option. 

The following three examples show how to load programs that call SYMDUMP. 
Example 1: 

If you are not expanding blank common and do not need to specify a SEGLDR HEAP directive 
on the SEGLDR command line for any other reason, you do not need to specify a SEGLDR 
HEAP or STACK directive. The following example shows a SEGLDR command line without 
HEAP or STACK directives: 

segldr -1 libdb.a *.o 

Example 2: 

If you are expanding blank common, you need to specify SEGLDR STACK and HEAP direc- 
tives. The following example shows a SEGLDR command line that can be used if the program 
expands blank common. 

segldr -I libdb.a -D t, STACK^3000+0;HEAP=10000+O tt *,o 

This example shows settings that should provide enough stack and heap space for SYMDUMP 
to run, assuming that your program is an average large application that has as many as 1000 
blocks. For applications with more blocks, 6 to 7 words per block over 1000 should be added 
to the heap setting. Optimal heap settings depend on the specific application. 

If running the application causes SYMDUMP to exit with the following error message, the 
value on the HEAP directive is too small: 

HP ALLOC failed; return status = i 

Example 3: 

If a SEGLDR DYNAMIC directive is used, the stack and heap cannot expand, so a SEGLDR 
STACK or HEAP directive may also be needed. Refer to the previous example for information 
about expanding the stack and heap. To load the heap prior to blank common, use 
DYNAMIC^// on SEGLDR s -D option, as shown in the following example: 

segldr -1 libdb.a -D "DYNAMIC*//" *.o 

For more information on SEGLDR, see the Segment Loader (SEGLDR) Reference Manual, publication 
SR^0O66. 

EXAMPLES 

The following example shows how to call SYMDUMP from a Fortran program when passing a character 
descriptor 

character*30 string 
integer abtfl 

string = '-s test -B -b STRING* 
abtfl = 1 
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C CHARACTER VARIABLE 
call symdump (string, abtfl) 

C CHARACTER CONSTANT 
call symdump (M outfile -V) 

The following example shows how to call SYMDUMP from C: 

extern void SYMDUMPO; 

int abtjlag = 1; 
char ^string; 

string = ,f -s a.out -V tt ; 
SYMDUMP (suing, &abt flag); 

The following example shows how to call SYMDUMP from Pascal when passing a conformant array: 

type 

stringjype = packed array [1.30] of char; 
var 

abort.flag: boolean; 

procedure symdump (var string: stringjype; var flag: boolean); 
imported (SYMDUMP); 

abortjSag := true; 

string [1..20] := *-s test -y STRING -Y*; 

string [21] := chr (0); (* must null terminate the string *) 

symdump (string, abort_flag); 

IMPLEMENTATION 

This routine is available only to users of the UNICOS operating system. 
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NAME 

TREK - Lists all subroutines active in the current calling sequence 

SYNOPSIS 

CALL TRBK [(arg)] 

DESCRIPTION 

arg Address of dataset name or unit number 

TRBK prints a list of all subroutines active in the current calling sequence from the currently active 
subprogram. It also identifies the address of the reference. You can specify a unit (arg) to receive the 
list. If you do not specify a unit, the list is printed to the user logfile or message log. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

TRBKLVL - Returns information on current level of calling sequence 
SYNOPSIS 

CALL TRTXKlsVlsitrbktabtQrglisumtuStMme 
DESCRIPTION 

trbktab Current level's Traceback Table address. On exit, current level's caller's Traceback Table 
address. Zero if the current level is a main-level routine. 

arglist Current level's argument list address. On exit, current level's caller's argument list address. 
Zero if the current level is a main-level routine. 

status <0 if error 

=0 if no error 

>0 if no error and the current level is the main level 
name Current level's name (ASCII, left-justified, blank-filled) 
calladr Parcel address from which the call to the current level was made 
entpnt Parcel address of the current level's entry point 

seqnum Line sequence number corresponding to the call address (0 indicates none) 
numarg Number of arguments or registers passed to the current level 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

XPFMT - Produces a printable image of an Exchange Package 

SYNOPSIS 

CALL XPFMT(address, in, out, mode) 

DESCRIPTION 

address The nominal location of the Exchange Package to be printed as the starting Exchange Pack- 
age address. The output buffer contains an 8-character field at the beginning of each line of 
the Exchange Package to indicate a CRAY address. The binary number in address is used 
to fill these eight characters of the first line of the Exchange Package in the output buffer 
and is incremented to fill each succeeding line of the output buffer. This is not the address 
of the 16-word buffer containing the Exchange Package to be formatted. 

A 16-word integer array containing the binary representation of the Exchange Package 

An integer array, dimensioned (8,0:23), into which the character representation of the 
Exchange Package is stored Line 0 is a ruler for debugging and is not usually printed. 

The first word of each line is an address and need not always be printed. 

An integer word indicating the mode in which the Exchange Package is to be printed. 'Y'L 
forces the Exchange Package to be formatted as a CRAY Y-MP Exchange Package; 'X'L 
forces the Exchange Package to be formatted as a CRAY X-MP Exchange Package; *S'L 
forces the Exchange Package to be formatted as a CRAY-1 Exchange Package; 0 means that 
the subprogram is to use the Exchange Package contents to deduce the machine type. 

XPFMT produces a printable image of an Exchange Package in a user-supplied buffer. A and S regis- 
ters appear in the buffer in both octal and character form; in the character form, the contents of the 
register are copied unchanged to the printable buffer. The calling program is responsible for proper 
translation of unprintable characters. Parcel addresses have a lowercase a, b, c, or d suffixed to the 
memory address. 

You can specify that the Exchange Package be formatted as a CRAY X-MP or CRAY-1 Exchange Pack- 
age, or you can allow XPFMT to determine which format to use, based on the values in the Exchange 
Package. Values within the Exchange Package determine the Exchange Package format. XPFMT 
assumes that the Exchange Package was produced by or for a CRAY X-MP computer system if either 
the data base address or the data limit address is nonzero. Otherwise, it assumes that the Exchange 
Package was produced by or for a CRAY-1 computer system. 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 



in 
out 

mode 
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SUBROUTINE SUBl(INTXP,OUTXP) 

INTEGER ENTXP(16),OUTXP(8,0:23),IADDR,IMODE 

address to use in output array 

IADDR = 8700 
let processor deduce machine type 

IMODE = 0 

pass the input Exchange Package to XPFMT and get the formatted 
version to print in OUTXP 

CALL XPFMT(IADDR,INTXP,OUTXP,IMODE) 

print the output of the XPFMT routine 

PRINT l,OUTXP 
1 FORMAT(24(lX,8A8/)) 
END 
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17. SYSTEM INTERFACE ROUTINES 



System interface routines are grouped into the following categories: 

• Job control language (JCL) symbol routines 

• Control statement processing routines 

• Job control routines 

• Floating-point interrupt routines 

• Bidirectional memory transfer routines 

• Special purpose interface routines 

JOB CONTROL LANGUAGE SYMBOL ROUTINES 

The JCL symbol routines manipulate JCL symbols for conditional JCL statements. 

JSYMSET changes a value for a JCL symbol- JSYM GET allows a user program to retrieve JCL symbols. 

CONTROL STATEMENT PROCESSING ROUTINES 

Control statement processing routines place control statement elements in appropriate memory locations 
to perform the specified operations. These routines, CRACK, PPL, and CEXPR, can also process direc- 
tives obtained from some source other than the control statement file ($CS). 

Control statement cracking routines take the uncracked image from the JCCCI field and crack it into the 
JCCPR field. The Job Communication Block (JCB) contains the control image in JCCCI. JCDLIT is a 
flag indicating whether or not literal delimiters are to be retained in the string. 

The following table contains the purpose, name, and entry of each control statement processing and 
cracking routine. 



Control Statement Processing and Cracking Routines 


Purpose 


Name 


Entry 


Crack a control statement 


CCS 


CCS 


Process control statement parameter 
values 


GETPARAM 


GETPARAM 


Crack a directive 


CRACK 


CRACK 


Process a parameter list 


PPL 


PPL 


Crack an expression 


CEXPR 


CEXPR 
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JOB CONTROL ROUTINES 

Job control routines perform functions relating to job step termination, either causing a termination or 
instructing the system on how to handle a termination. Unless otherwise specified, these routines are 
called by address. No arguments are returned. 

The following table contains the purpose, name, and entry of each job control routine. 



Job Control Routines 


Purpose 


Name 


Entry 


Request abort with traceback 


ABORT 


ABORT 


Terminate a job step and advance 


END 


END 


Continue exit processing after a reprievable 
condition 


ENDPRV 


Exit from a Fortran program 


EXIT 


EXIT 


Request abort 


ERREXIT 


ERREXIT 


Declare a job rerunnable or not 
rerunnable 


RERUN 


RERUN 


Instruct the system to begin or 
cease monitoring jobs for functions 
affecting rerunnability 


NORERUN 


Conditionally transfer control to a 
specified routine 


SETRPV 


SETRPV 



FLOATING-POINT INTERRUPT ROUTINES 

Floating-point interrupt routines allow you to test, set, and clear the Floating-point Inteirupt Mode flag. 
Subroutine linkage is call-by-address. 

The following table contains the purpose, name, and entry of each floating-point interrupt routine. 



Floating-point Interrupt Routines 


Purpose 


Name 


Entry 


Temporarily prohibit floating-point 
interrupts 


CLEARFI 


CLEARFI 


Temporarily permit floating-point 
interrupts 


SETFI 


Temporarily prohibit floating-point 
interrupts for a job 


CLEARFIS 


CLEARFIS 


Temporarily enable floating-point 
interrupts for a job 


SETFTS 


Determine whether floating-point 
interrupts are permitted or 
prohibited 


SENSEFI 


SENSEFI 
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BIDIRECTIONAL MEMORY TRANSFER ROUTINES 

Bidirectional memory transfer routines test, set, and clear the Bidirectional Memory Transfer Mode flag. 
Subroutine linkage is call-by-address, 

NOTE 

These routines are only effective on CRAY Y-MP and CRAY X-MP computer systems, which have 
hardware support for bidirectional memory transfer. They are no-ops on other mainframe types. 

The following table contains the purpose, name, and entry of each bidirectional memory transfer rou- 
tine. 



Bidirectional Memory Transfer Routines 


Purpose 


Name 


Entry 


Temporarily disable bidirectional 
memory transfers 


CLEARBT 


CLEARBT 


Temporarily enable bidirectional 
memory transfers 


SETBT 


Permanently disable bidirectional 
memory transfers 


CLEARBTS 
SETBTS 


CLEARBTS 


Permanently enable bidirectional 
memory transfers 


Determine current memory transfer 
mode 


SENSEBT 


SENSEBT 



SPECIAL-PURPOSE INTERFACE ROUTINES 

The following table contains the purpose, name, and entry of each special-purpose interface routine. 
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Special-purpose Interface Routines 


Purpose 


Name 


Entry 


Return the Job Accounting Table 


ACTTABLE 


ACTTABLE 


Program a Cray channel on an IOS 


DRIVER 


DRIVER 


Turn on or off the class of 
messages to the user logfile 


ECHO 


ECHO 


Allow a job to suspend itself 


ERECALL 


ERECALL 


Return lines per page 


GETLLP 


GETLLP 


Return the integer ceiling of a 
rational number formed by two 
integer parameters 


ICEIL 


ICEIL 


Allow a job to communicate with 
another job 


UCOM 


UCOM 


Return the job name 


JNAME 


JNAME 


Load an absolute program from a 
dataset containing a binary image 


LGO 


LGO 


Return the memory address of a 
variable or an array 


LOC 


LOC 


Manipulate a job's memory allocation 
and/or mode of field length 
reduction 


MEMORY 


MEMORY 


RpfiiTTi tilt* fvlitinn for a nrpvjfttidv 

accessed permanent dataset 






to the overlay entry point 


OVERLAY 


OVERLAY 


Enter a message (preceded by a message 

Tirpfty^ in ttip impr and cvcfp>m lntrfilp^ 

L/lv-UA J 111 Ulv Uovl CUl^J- OW/lkl JV/£^UJVd 


REMARK 


REMARK 


Enter a message in the user and 
system logfiles 


REMARK2 


Enter a formatted message in the 
user and system logfiles 


REMARKF 


REMARKF 


Return Cray machine constants 
(machine epsilon; smallest and 
largest normalized numbers.) 


SMACH 
CMACH 


SMACH 


Test the sense switch 


SSWITCH 


sswttch 


Make requests of the operating 
system 


SYSTEM 


SYSTEM 
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NAME 

ABORT - Requests abort with traceback 

SYNOPSIS 

CALL ABORT[(fog)] 

DESCRIPTION 

log Log file message 

ABORT requests abort with traceback and provides an optional log file message. The optional user- 
supplied log file message is written to both user and system log files. The message is written in the 
same format in which it was sent 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

ACTTABLE - Returns the Job Accounting Table (JAT) 
SYNOPSIS 

CALL ACTTABLE(array t count[,tac,tasz t gut t guszfutfu$2]) 
DESCRIPTION 

array An array in which to write a copy of the JAT 

count Count; the first count words of the JAT are returned in the array. If count is greater than 
the size of the JAT, the array is padded with minus ones. 

tac Address in which to write a copy of the Task Accounting Table 

tasz Length of the task accounting information to copy in words. No more than tasz words are 

returned. 

gut Address in which to write a copy of the Generic Resource Table 

gusz Length of the Generic Resource Table information in words. No more than gusz words are 

returned. 

fut Address in which to write a copy of the Fast Secondary Storage (FSS) device utilization 

information 

fusz Length of the FSS device utilization information area in words. No more than fusz words 

are returned. 

You can specify array and count without requesting any of the optional information with the other 
parameters. However* to request any of the optional information, you must enter values for all six of 
the optional parameters, entering a zero length for those you do not want. 

EXAMPLE 

The call to ACTTABLE in the following example returns information from the JAT and six words from 
the Task Accounting Table. Since the size parameters (GUSZ and FUSZ) are set to zero* no FSS or 
Generic Resource Table information is returned. 

PROGRAM ACTTAB 

IMPLICIT INTEGER (A-Z) 

PARAMETER (COUNT = 10) 
PARAMETER (TASZ = 6) 
PARAMETER (GUSZ - 0) 
PARAMETER (FUSZ = 0) 
DIMENSION ARRAY(60), TAC(6) 

CALL ACTTABLE(ARRAY,COUNTTAC,TASZ,JUNK t GUSZJUNK t FUSZ) 

STOP 

END 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

CCS - Cracks a control statement 

SYNOPSIS 

CALL CCS 

DESCRIPTION 

No parameters. CCS aborts the job if errors are encountered. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 



SR-0113 



D 



CEXPR (3COS) 



CEXPR(3COS) 



NAME 

CEXPR - Cracks an expression 

SYNOPSIS 

CALL CEXPR(char,0Ut t lmt t size) 

DESCRIPTION 

char Expression character-string array (terminated by a 0 byte) 
out Reverse Polish Table array for output 

Imt Upper limit to the size of the Reverse Polish Table 

size Actual size of the Reverse Polish Table on return 

CEXPR transforms an expression character string (1 right-justified character per word) to a Reverse Pol- 
ish Table. 

An expression can contain a mixture of symbols, literals, numeric values, and operators. Expressions 
handled by this routine resemble Fortran in syntax. 

Operator hierarchy follows Fortran rules and does parenthesis nesting. Symbols are defined as 1- to 8- 
character strings having unknown value to CEXPR. CEXPR simply flags the strings for the caller. The 
first character cannot be numeric. Literals are 1- to 15-character strings enclosed by double quotes ("). 

A character string consisting of numeric digits is taken as a 64-bit integer. A trailing B signifies an 
octal number. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

CLEARBT, SETBT - Temporarily disables/enables bidirectional memory transfers 

SYNOPSIS 

CALL CLEARBT 
CALL SETBT 

DESCRIPTION 

CLEARBT temporarily disables bidirectional memory transfers. SETBT temporarily enables bidirectional 
memory transfers. 

These routines are local to the current job step. The system restores the most recent mode setting at the 
start of the next job step. No arguments are required or returned. 

IMPLEMENTATION 

These routines are available only to users of the COS operating system. 
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NAME 

CLEARBTS, SETBTS - Permanently disables/enables bidirectional memory transfers 

SYNOPSIS 

CALL CLEARBTS 
CALL SETBTS 

DESCRIPTION 

CLEARBTS permanently disables bidirectional memory transfers. SETBTS permanently enables bidirec- 
tional memory transfers. 

The results of these routines are permanent and are propagated through job steps. The system does not 
alter the mode setting unless another bidirectional memory transfer control subroutine is called or a 
MODE control statement is executed. No arguments are required or returned. 

IMPLEMENTATION 

These routines are available only to users of the COS operating system. 
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NAME 

CLEARFI, SETFI - Temporarily prohibits/permits floating-point interrupts 

SYNOPSIS 

CALL CLEARFI 
CALL SETFI 

DESCRIPTION 

CLEARFI temporarily prohibits floating-point interrupts. SETFI temporarily permits floating-point inter- 
rupts. 

These routines are local to the current job step. The system restores the most recent mode setting at the 
start of the next job step. No arguments are required or returned. 

IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 

CLEARFIS, SETFIS - Temporarily prohibits/permits floating-point interrupts for a job 

SYNOPSIS 

CALL CLEARFIS 
CALL SETFIS 

DESCRIPTION 

CLEARFIS prohibits floating-point interrupts for a job until they are enabled or until the job terminates. 

SETFIS enables floating-point interrupts until they are explicitly disabled or until the job terminates. 

The results of these routines are propagated through job steps. The system does not alter the mode set- 
ting until another floating-point interrupt control subroutine is called or a MODE control statement is 
executed. No arguments are required or returned, 

IMPLEMENTATION 

These routines are available only to users of the COS operating system. 
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NAME 

CRACK - Cracks a directive 
SYNOPSIS 

CALL CRkCK{ibi$Men>cbuf t clenftagl4flag]) 
DESCRIPTION 

ibuf Image of the statement to be cracked 

Hen Integer length (in words) of the statement image to be cracked. Maximum value is 10 

words. 

cbvi Array to receive the cracked image 
clen Integer length in words of the array cbuf 

flag Integer variable to receive completion status. The Return Value flag has the following 

meanings: 

0 Normal termination 

1 No error; continuation character encountered. 

2 Invalid character encountered 

3 Premature end-of-input line 

4 CRACK buffer overflow 

5 Unbalanced parentheses 

6 Input buffer too large 

dflag Integer flag indicating that literal string delimiters are to be preserved in the cracked image. 

If set to 0 or omitted, quotes are not included in the cracked string. If set to 1, all quotes 
are included in the string. 

CRACK reformats (parses) a user-supplied string into verb, separators, keywords, and values. The 
cracked directive is placed in a user-supplied buffer and returns the status of the crack to the caller, 
CRACK can be called repeatedly to process a control statement across several records. 

NOTES 

Each keyword or positional parameter should be assigned a separate word. Keywords or positional 
parameters of more than 8 characters must be assigned 1 word for each 8 characters plus 1 for any 
remaining characters if the length is not a multiple of 8 characters. Each separator must also be 
assigned a separate word. 

flag should be set to 0 before the first call to CRACK and should not be changed (except by CRACK) 
until after the last call to CRACK. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

DELAY - Do nothing for a fixed period of time 

SYNOPSIS 

CALL DELAY(/nsrime) 

DESCRIPTION 

mstime Delay time in milliseconds, mstime must be in the range 0 to I 24 -!. 

DELAY requests that the executing task not be rescheduled to a CPU until mstime milliseconds have 
elapsed, 

IMPLEMENTATION 

This routine is only available to users of the COS operating system. 
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NAME 

DRIVER - Programs a Cray channel on an I/O Subsystem (IOS) 

SYNOPSIS 

CALL Dm\ER(arrayJentry f status) 

DESCRIPTION 

array First element of the integer parameter block array. The airay is lentry words long. In all 
cases, FUNC, PLEN, and LN are required in the parameter block* and COSS is returned in 
the User Driver Parameter Block (DRPB) (see the COS Reference Manual, publication SR- 
0011, for more information on DRPB). DP is always sent to the driver and returned to you. 
See individual driver specifications for the use of the word and other field requirements. 

For the Fortran user, FUNC, DIR, and COSS are literal strings. (For example, set FUNC to 
*CFN$OPE' and DIR to 'DIR$INP' to open an input channel. , DRS$RSV in COSS means 
the channel is reserved for another job.) 

The 'CFN$OPE* subfunction opens a channel; a job cannot access a channel until it opens 
the channel. DRNM, TO, DIR, and OPD are required. 

The 'CFN$CLS* subfunction closes a channel. Any open channels are closed during termi- 
nation. DIR is required. 

The *CFN$RD', 'CFNSRDH', and *CFN$RDD* subfunctions read data. BAD and DLN are 
required; TLN is returned. For read, either the channel is read to Central Memory or data is 
moved from IOS Buffer Memory to Central Memory (if a read/hold was done prior to this 
read). For read/hold, a second read is performed, and the data is held in Buffer Memory 
for a subsequent read. For read/read, a second read to Central Memory is done. 

The >CFN$WT% 'CFN$WTH\ and 'CFN$WTD' subfunctions write data. BAD and LN are 
required; TLN is returned. For write, data is written to the channel from Central Memory 
or Buffer Memory (if a write/hold was done prior to this request). For write/hold, a second 
buffer of data is moved to and held in Buffer Memory for a subsequent write. For 
write/write a second write is performed from Central Memory. 

The 'CFNSDMIN'-'CFNSDMAX' subfunctions are defined by the driver. DFP and DIR are 
required. 

lentry Length of the parameter block entry in array; user-specified integer variable. 

status Status; integer variable set by the system. On return, status is 0 if no errors have occurred, 
and the job must poll COMS for nonzero. When COMS is nonzero, the driver has com- 
pleted the request and the driver status is in DRS. See the individual driver specifications 
for driver status. If status is nonzero on return, COSS contains the error code and the 
request is not sent to the driver. 

If no errors have occurred, and if status is nonzero on return, COSS contains the error code. 

This capability is available only with devices connected to the Master I/O Processor (MIOP). This is a 
privileged function available to all single-tasked job steps. It is prohibited to multitasking job steps. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

ECHO - Turns on and off the classes of messages to the user logfile 
SYNOPSIS 

CALL ECHO('ON , Lt 1 param-flrroy], , OFF , Lt^ara>n-airay]) 
DESCRIPTION 

param-array Optional array of message class names or 'ALL'. Message class names are defined in 
the COS Reference Manual, publication SR-0011. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 



SR-0113 



17-16 



D 



END(3U) 



END(3U) 



NAME 

END, ENDRPV - Terminates a job step 

SYNOPSIS 

END 

CALL ENDRPV 
DESCRIPTION 

END terminates a job step and advances to the next job step. 

ENDRPV continues normal exit processing after a reprievable condition has been processed. This exit 
processing can be the result of normal termination or abort processing. 

IMPLEMENTATION 

END is available to users of both the COS and UNICOS operating systems. 
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NAME 

ERECALL - Allows a job to suspend itself until selected events occur 
SYNOPSIS 

CALL ERECALLtfunc,status,sevents,to t oeventsJevents) 
DESCRIPTION 

func User-specified integer variable to define the requested information or action 

'DISABLE' Disables event monitoring. All other words are 
ignored. 

TSNABLE* Enables event monitoring or changes the events to be 
monitored, levents and sevents are required. If 
levents is 0, time-out is the only enabled event; time-out is 
enabled to prevent a job remaining indefinitely in recall. 
levents and oevents are returned by the system, to 
is ignored. 

'RECALL' Places the job in recall. An error is returned in 
status if monitoring is disabled, to is required; 
sevents is ignored, levents and oevents are set by 
the system. If to is 0, an installation-defined default, 
I@TODEF, is used. If to is specified, 
but less than the 
installation-defined minimum, 
I@TOMIN, the installation 

minimum is used with no notification. If levents is 0 on 
return, time-out is the only event that occurred. 

"RETURN* Requests that levents and oevents be set 

by the system; all other words are ignored. An error is returned in 
status if monitoring is disabled. 

status Status; an integer variable set by the system. Status is 0 if no errors occurred; otherwise, 
see the Event Recall Parameter Block (ERPB) definition in the COS Reference Manual, pub- 
lication SR-0011, for error codes. The codes are returned as blank-filled literal strings (for 
example, ERER$BFN is returned as *ERER$BFN'). 

sevents User-specified integer array containing the events to be monitored, levents is the number of 
events specified in sevents. The events can be selected from the following: 

U* Interjob message received 

TIO' Unsolicited operator message received (Deferred implementation) 

"OR* Operator reply received (Deferred implementation) 

The following events are privileged: 

'CW Channel driver done 

1Q> SDT placed in input queue (Deferred implementation) 

'OQ' SDT placed in output queue (Deferred implementation) 

to Time-out duration in milliseconds (rightmost 24 bits); user-specified integer variable. 

oevents Integer array set by the system to the occurred events, levents is the number of event 
words that have been placed in oevents by the system. See sevents for possible values. 
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[events Integer value specifying the number of events in either sevents or oevents. For ENABLE, 
set levents to the number of event words that you have placed in sevents. On return from 
ENABLE, RECALL, and RETURN, levents is the number of event words that the system has 
placed in oevents. 

ERECALL allows a job to suspend itself until one or more selected events occur. 

NOTE 

This routine is available to all single-tasking job steps; it is prohibited to multitasking job steps. 

When event monitoring is enabled, the system monitors selected events for a job, keeping track of 
which ones have occurred. Monitoring is disabled at the beginning of each job step and can be enabled 
by making a system request, specifying the events to monitor. Once monitoring is enabled, a job can 
make a system request to change the events that are to be monitored, get a map indicating which of the 
monitored events occurred, go into event recall until one of the selected events occurs, or disable moni- 
toring. 

When monitoring is enabled, a map of occurred events is returned to you and discarded by the system. 
If monitoring was disabled when the enable occurred, the map is 0. 

When the events to be monitored are changed, a map of occurred events is returned to you and dis- 
carded by the system. 

When a map of occurred events is requested, the map is returned to you and discarded by the system. 

When recall is requested and the map of occurred events is 0, the job is suspended for an event until 
one of the events occurs. If the map is nonzero, the map is returned to you immediately and discarded 
by the system. 

When recall is disabled, the map of occurred events is discarded by the system. 



IMPLEMENTATION 

This routine is available only to users of the COS operating system. 



SEE ALSO 

The COS Reference Manual, publication SR-0011 
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NAME 

ERREXTT - Requests abort 

SYNOPSIS 

CALL ERREXIT 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

EXIT - Exits from a Fortran program 

SYNOPSIS 

CALL EXIT 

DESCRIPTION 

EXIT ends the execution of a Fortran program and writes a message to the log file (COS) or stdout 
(UNICOS). Under COS, the message is as follows: 

UT003 - EXIT CALLED BY routine name 

The UNICOS message is as follows: 

EXIT (called by routine name, line n) 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

GETARG - Return Fortran command-line argument 

SYNOPSIS 

ichars = GETARG(i,c) 
ickars= GET ARG(i,c .size) 

DESCRIPTION 

ichars Number of non-null characters in the string returned 
i Number of (he argument to return 

c Character variable or integer array in which to return the command-line argument 

size If c is an array, the number of elements in that array 

GETARG returns the i-th command-line argument of the current process. Thus, if a program is 
invoked with the following command line, GETARG(2,C) returns the string arg2 in the character vari- 
able C: 

foo argl arg2 arg3 

SEE ALSO 

GETOPT(3C) 

IMPLEMENTATION 

This routine is available only to users of the UNICOS operating system. 



SR-0113 



17-22 



D 



GETLPP(3COS) 



OETLPP(3COS) 



NAME 

GETLPP - Returns lines per page 

SYNOPSIS 

(pp=GETLPP( ) 

DESCRIPTION 

Ipp Lines per page (type integer) 

GETLPP returns the lines per page from field JCLPP of the Job Control Block (JCB) in register SI. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

GETPARAM - Gels parameters 
SYNOPSIS 

CALL GETPARAM(table,number,param) 
DESCRIPTION 

table The Parameter Control Table (PCT), dimensioned (Sjiumber) and containing the following 
in each 5-element row: 

1 A left-justified, zero-filled keyword 

2 A default value for use if the keyword is missing 

3 A default value for use if the keyword is present but not 

assigned a value 

4 Subscript of param into which the first parameter value is 

stored 

5 Index of the last word the the param array to be used for 
storing the parameter value 

If item 2 is negative, GETPARAM requires the keyword to be on the control statement. 

If item 3 is negative, GETPARAM does not allow the use of the keyword alone (as in 
"....keyword,..."). 

Either item 2 or 3 can be 0; GETPARAM does not distinguish between Os and any other 
positive values such as character strings, but the caller can test them after GETPARAM 
returns. 

If items 2 and 3 are 0 and 1, or 1 and 0, respectively, GETPARAM does not allow the key- 
word to be followed by an 9 =\ The keyword must be simply absent or present. 

If item 1 is a 64-bit mask (that is, 177777 7777 7777 7777 7777B), the value given as the key- 
word is returned in the control table* When an entry of this type is specified in the control 
table, the number of parameters is limited to one. 

If item 1 is given a value of 0, the entry describes a positional parameter. Entries of this 
nature must be described in positional order. 

If bit 2 in item 4 (that is, 020000 0000 0000 0000 0000B) is set, the parameters following the 
keyword are defined to be secure and are edited out before the statement is echoed to the 
user's logfile. If bit 3 is set, it indicates that a NULL character in the first word of a param- 
eter value should be considered a string terminator. 

number The number of parameters described in the control table. If set to 0, GETPARAM does not 
allow any parameters on the control statement. 

param An array sufficiently large to receive all the parameter values 

GETPARAM processes control statement parameter values from an already cracked control statement. 
If the statement has been continued across card images, GETPARAM automatically requests the next 
control statement and calls $CCS to crack it. Processing is determined by the rules set up by the PCT. 

The PCT indicates default values for unspecified parameters. Through the PCT, the caller also indicates 
the following: 

• If a parameter must be specified on the statement 

• If a parameter is positional or keyword 

• If a keyword parameter can have an equated value 

• If a keyword parameter must have an equated value 

• If any parameters are allowed 
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EXAMPLE 

Example of control table definition in Fortran: 



INTEGER PERMFDLE(2) PARAMS(15), TABLE(5,4), INPUT, LIBRARY(IO), LIST 
EQUIVALENCE(PARAMS(1)JNPUT), 

* (PARAMS (2) ,FERMFTLE) , 

* (PARAMS(4),LIBRARY(1)), 

* (PARAMS(14),LIST) 
DATA PARAMS/15*0/ 

DATA(TABLEa,l),I=1.5y , I , L, , $INV$IN , L f l,l/, 

(TABLEa > 2)J-l t 5)/ , P , L t 0 t -lA3/, 

(TABI^3)J-l»S)rUB 9 U-l/SniJB f L 9 4 v l3/. 

(TABLE(I,4),I= 1 ^/TIST'LA 1 , 14, 14/ 
CALL GETPARAM (TABLE,4,PARAMS) 

This table (for a hypothetical program) tells GETPARAM that the only keywords to be accepted are I, P, 
LIB, and LIST. The -1 value means that P cannot appear alone (without an equal sign) and that LIB (with or 
without an equal sign) must appear in the control statement. 

In this table, only one word is provided for the I parameter; therefore, if l-xxx appears in the control state- 
ment, the option xxx must not exceed 8 characters. The 2 words provided for the P parameter allow for the 
maximum of 16 characters or for two subparameters (up to 8 characters each) separated by a colon in the 
control statement. Ten words are provided for the LIB parameter so that up to ten subparameters (or five 2- 
word parameters) are allowed in the control statement, GETPARAM requires the keyword LIST to appear 
alone or not at all. If LIST is specified, the value returned in the Parameter Value Table is 1. LIST cannot be 
followed by an equal sign. 

NOTES 

The following two subparameters cannot be distinguished from one another in the PARAMS table: 

A=A1234567:B1234567(Two 8-character parameters) 
A=A1234567B1234567(One 16-character parameter) 
Thus, the caller is responsible for restricting such cases. 

The output array PARAMS must be as large as the largest subscript. If PARAMS is initialized to Os, the 
programmer can determine how many words are returned by GETPARAM for multiword parameters 
such as P and LIB. 

Because Fortran array numbering starts with 1, the array's base address is reduced by 1 in GETPARAM. 
Therefore, the CAL user must supply the table address + 1 (This is not true for $GP) in order to use 
labels directly in lieu of the Fortran subscripts* 

The following characters should not be used in keywords: the colon, parentheses, period, comma, apos- 
trophe, caret, and equal sign. 

GETPARAM aborts if the control statement violates either the standard control statement syntax rules or 
the additional rules imposed by the PCT. If there are no eirors, the array is filled with values from the 
control statement and/or with default values. The PCT is not altered by GETPARAM. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

IARGC - Returns number of command line arguments 

SYNOPSIS 

iargs = IARGC( ) 

DESCRIPTION 

iargs Number of command line arguments passed to the program 

If a program is invoked with the following command line, IARGC returns 3; 
foo argl arg2 arg3 

SEE ALSO 

GETOPT(3C) 

IMPLEMENTATION 

This routine is available only to users of the UNICOS operating system. 
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NAME 

ICEIL - Returns integer ceiling of a rational number 

SYNOPSIS 

i=ICEJL<jJt) 

DESCRIPTION 

j The numerator of a rational number 

k The denominator of a rational number 

ICEIL returns the integer ceiling of a rational number formed by two integer parameters. ICEIL is an 
integer function. 

The value of the function / is the smallest integer larger than or equal to 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

UCOM - Allows a job to communicate with another job 

SYNOPSIS 

CALL UCQM(status,array,lentry,nentry) 

DESCRIPTION 



status status is a literal value of the error (or, in the case of multiple errors, the literal value of the 
last error to occur). If status is not equal to UMS$OK, STAT contains the literal error code. 
If multiple parameter blocks are used, all STAT fields must be examined if status is 
nonzero. 

array First element of the integer parameter block array. An installation-defined maximum 
number of parameter blocks (I@MPBS) can be specified in array. The array is larray 
words long, and each of the nentry parameter blocks in it is lentry words long. See the 
Interjob Communications Parameter Block (DPB) table definition in the COS Reference 
Manual, publication SR-0011, for a description. You may ignore LINK; the system links the 
entries together for the user* In all cases, FUNC, RID, and PLEN are required in each 
parameter block, and the system sets STAT in each parameter block. The array length must 
equal lentry * nentry. 

FUNC and STAT are literal strings (for example, set FUNC to 'UMSOPEN* to open a path. 



lentry 



nentry 



UM$NOP' Subfunction is a no op. 

UMSREO Subfunction marks the job as receptive. RCB is required; all other words 
are ignored. 

TJM$OPEN' Subfunction initiates an attempt to open a communication path with 
another job. HLEN, TID, and NCB are required; all other words are 
ignored. 

TJM$ACCE' Subfunction accepts a request from another job to open communication. 
TID, HLEN, and NCB are required; all other words are ignored. 

TJM$REJE' Subfunction rejects a request from another job to open communication. 
TID is required; all other words are ignored. 

UM$SNDM* Subfunction sends a message to another job. NCB, TID, BADD, and BLEN 
are required; all other words are ignored. 

UM$SNDL' Subfunction sends a message to an attached job's logfile. This is a 
privileged function. TID, OVR, FCS, FCU, CLS, and BADD are required; 
all other words are ignored. 

TJM$CLOS* Closes a communication path. Either NCB and TID or neither are 
required; all other words are ignored. If NCB and TID are specified, only 
the path determined by RID and TED is closed; otherwise all communica- 
tion paths with RID are closed. 

TJM$END' Subfunction marks the job as not receptive. All other words are ignored. 
Existing communication paths are not affected. 

Length of each parameter block entry in array; user-specified integer variable, lentry must 
equal LE@UPB (LE@UPB is defined in SSYSTXT as the length of the Interjob Communi- 
cations Parameter Block). 

Number of parameter blocks in the array; user-specified integer variable. Default is 1. 
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status Status; an integer variable set to 0 if no errors occurred. If status is nonzero, STAT con- 
tains the error code. If multiple parameter blocks are used, all STAT fields must be exam- 
ined if status is not equal to UMSSOK (if no errors occurred, sfctfi^IJMS$OK). 

NOTE 

UCOM is available to all single-tasking job steps. At this time, interjob communication is prohibited to 
multitasking job steps. 

SEE ALSO 

The COS Reference Manual, publication SR-0011 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

ISHELL - Executes a UNICOS shell command 

SYNOPSIS 

ISTAT = JSHELUcommand) 

DESCRIPTION 

ISHELL has the following argument: 
command Command to be given to the shell 

ISHELL passes command to the shell sh(l) as input, as if command was entered at a terminal. The 
current process waits until the shell .has completed, then returns the exit status. 

EXAMPLE 

ISTAT = ISHELL('rm -f * o') 

IMPLEMENTATION 

This routine is available only to users of the UNICOS operating system. 
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NAME 

JNAME - Returns the job name 

SYNOPSIS 

name*xJNAME(resuli) 

DESCRIPTION 

name Job name; left-justified with trailing blanks. 
result Returned job name 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 



JSYMSET, JSYMGET - Changes a value for a JCL symbol or retrieve a JCL symbol 



SYNOPSIS 



CALL JSYMSET(' sym'L,valUen]) 
CALL JSYMGETC sym'UvalUenl) 



DESCRIPTION 



sym 
val 



Valid JCL symbol name 

For JSYMSET, the actual value assigned to the symbol. For JSYMGET, val receives the 
actual value of the symbol if the value buffer is large enough and the symbol currently has 
a value. 



ten 



For JSYMSET, the length of val in words (elements). For JSYMGET, the length of the 
value buffer in words (elements), ten is changed to the actual length of the symbol's value 
(less than or equal to the value buffer). 



JSYMSET allows you to change a value for a JCL symbol. Hie value specified is the actual value given 
to the symbol; no evaluation is performed. 

JSYMGET allows user programs to retrieve JCL symbols. JSYMGET also allows for the creation of JCL 
symbols if they do not exist. See the COS Reference Manual, publication SR-0011, for more information 
on JCL symbol definitions, 

IMPLEMENTATION 

These routines are available only to users of the COS operating system. 
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NAME 

LGO - Loads an absolute program from a dataset containing a binary image as the first record 

SYNOPSIS 

CALL LGO('dn'L) 

DESCRIPTION 

The dataset name containing the absolute load module is represented by dn. LGO loads an absolute 
program from a local dataset containing die binary image as the first record. The loaded program is 
then executed. Control does not return to LGO. 

Security privileges may be required sometimes when using LGO might seem appropriate (specifically, if 
you attempt to open a dataset using SDACCESS), Use CALLCSP as a more general replacement for this 
routine. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

CALLCSP 
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NAME 

LOC - Returns memory address of variable or array 

SYNOPSIS 

address=LOC(arg) 

DESCRIPTION 

address Argument address (type integer) 

arg Argument whose address is to be returned 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

MEMORY - Manipulates a job's memory allocation and/or its mode of field length reduction 

SYNOPSIS 

CALL MEMORY(code t value) 

DESCRIPTION 

code Determines what information or action is requested (blank-filled) 

*UC value specifies the number of words to be added to (if value is positive) or 
subtracted from (if value is negative) the end of the user code/data area. 

'FL* value specifies the number of words of field length to be allocated to the job. 

If FL is specified and value is not, the new field length is set to the max- 
imum allowed the job, and the job is placed in user mode for the duration of 
the job step. 

'USER 4 The job is put in user-managed field length reduction mode, value is 
ignored. 

'AUTO' The job is put in automatic field length reduction mode, value is ignored. 

'MAXFL' The maximum field length allowed the job is returned in value* 

'CURFL' The current field length is returned in value. 

'TOTAL' The total amount of unused space in the job is returned in value. 

value An integer value or variable when code is *UC or 'FL'. An integer variable that is to con- 
tain a returned value if code is 'CURFL', 'MAXFL\ or 'TOTAL'. 

Memory can be added to or deleted from the end of the user code/data area by using the 'UC code. If 
the user code/data area is expanded, the new memory is initialized to an installation-defined value. 

The job's field length can be changed by use of the 'FL* code. The field length is set to the larger of 
the requested amount rounded up to the nearest multiple of 512-decimal words or the smallest multiple 
of 512-decimal words large enough to contain the user code/data. Logical File Table (LFT), Dataset 
Parameter Table (DSP), and buffer areas. The job is placed in user-managed field length reduction mode 
for the duration of the job step. 

The job's mode of field length reduction can be changed by use of either the 'USER* or 'AUTO' code. 
When 'USER' is specified, the job is placed in user mode until a subsequent request is made to return it 
to automatic mode. When 'AUTO' is specified, the job is placed in automatic mode, and the field 
length is reduced to the smallest multiple of 512-decimal words that can contain the user code/data, 
LFT, DSP, and buffer areas. 

The job's maximum or cunent field length can be determined by the 'MAXFL' or amount of unused 
space in the job can be determined by the TOTAL* code. 

The job is aborted if filling the request would result in a field length greater than the maximum allowed 
the job. The maximum is the smaller of the total number of words available to user jobs minus the 
job's Job Table Area (JTA) or the amount determined by the MFL parameter on the JOB statement. 
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EXAMPLE 

Example 1: 

CALL MEMORY('FL') 

The job's field length is set to the maximum allowed the job, and the job is placed in user mode for the dura- 
tion of the job step. 

Example 2: 

CALL MEMORYC AUTO') 

The job's field length is reduced to a minimum, and the job is placed in automatic mode. 

Example 3: 

CALL MEMORY('UC',-5) 
CALL MEMORY('UCMVAL) 

where IV AL is -5 

The job's user code/data area is reduced by 5 words. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

NACSED - Returns the edition of a previously-accessed permanent dataset 

SYNOPSIS 

erf=NACSED( ) 

DESCRIPTION 

NACSED returns edition number ed in binary form for the permanent dataset most recently accessed by 
a call to ACCESS. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

OVERLAY - Loads an overlay and transfers control to the overlay entry point 
SYNOPSIS 

CALL OVERLAYinLdnJevxJeVilfecam) 

DESCRIPTION 

n Number of characters in dn 

L Left-justified; zero-filled. 

dn Dataset in which the overlay resides. Must be a character constant, integer variable, or an 

array element containing Hollerith data of not more than 7 characters. 

levi Overlay level 1 (LEVI) 

lev 2 Overlay level 2 (LEV2) 

recall Optional recall parameter. To reexecute an overlay without reloading it, enter 6LRECALL. 
If the overlay is not currently loaded, it will be loaded. 

NOTES 

This routine is used to implement LDR-style overlays. Cray Research recommends conversion to 
SEGLDR-style segments whenever possible. See the Segment Loader (SEGLDR) Reference Manual, 
publication SR-0066. 

IMPLEMENTATION 

This routine is available to users of both the COS and the UNICOS operating systems. 

SEE ALSO 

ldovl(l) 

See the COS Reference Manual, publication SR-0011, for details of the OVERLAY routine. 
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NAME 

PPL - Processes keywords of a directive 
SYNOPSIS 

CALL PPL(cbitf t ctable,ltable putarrayjtattbl) 
DESCRIPTION 

PPL processes the keywords for a given directive. Processing is governed by the Parameter Description 
Table, which has the same format as the table GETPARAM uses, except that the length of the table 
used by PPL is seven words with the two extra words unused 

cbuf Array containing the cracked image (usually prepared by CRACK, which is described in 



ouiarray Array to receive parameter values 

stattbl Three-word completion status code. On the first-time call, you must initialize the Return 
Status Table to zero. If PPL returns a status that is not normal, and PPL is called again 
with the invalid values left in, it attempts to recover. 



ctable 



section 17) 
PPL control table 



liable 



Number of 7-word entries in PPL control table 



Array element Meaning 



1 



Return status code: 

0 Normal termination 

1 Required keyword not found 

2 Output keyword overflow 

3 Syntax error 

4 Unknown or duplicate keyword 

5 Unexpected separator encountered 

6 Keyword cannot be equated 

7 Keyword must have value 

8 Maximum of 64 keywords exceeded 

9 Invalid return status; cannot recover 



2 
3 



Keyword in error 
Ordinal keyword value 



IMPLEMENTATION 



This routine is available only to users of the COS operating system. 



SEE ALSO 



GETPARAM, CRACK 
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NAME 

REMARK2, REMARK - Enters a message in the user and system log files 

SYNOPSIS 

CALL REMARK2(message) 
CALL REMARK(message) 

DESCRIPTION 

message For REMARK2, message terminated by a 0 byte or a maximum of 79 characters. For 
REMARK, message terminated by a 0 byte or a 71-character message. 

REMARK2 enters a message in the user and system log files. REMARK enters a message preceded by 
the prefix 'UT008 - ' in the user and system logfiles. 

Under UNICOS, these routines write to stderr instead of the system logfile. 
IMPLEMENTATION 

These routines are available to users of both the COS and UNICOS operating systems. 
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NAME 



REMARKF - Enters a formatted message in the user and system logfiles 



SYNOPSIS 



CALL REMARKF(varfvar,lfvar 2 ,...fvar 12 1) 



DESCRIPTION 



fvar 



var 



Variable containing the address of a format statement for ENCODE 
Address of variable 



Up to 12 variables can be passed in arguments 2 through 13. The variables must be of type integer, 
real, or logical so that they each occupy only 1 word. The message is prefixed by 'UT009 - ' unless 
you supply a prefix. To supply the prefix, the characters 'b-b' (b=blank) must appear in columns 6 
through 8 of the formatted message. 



Sample Fortran calling sequences with user-supplied prefixes: 

10030 FORMAT ('CA001 - ',14, ' errors') 
ASSIGN 10030 TO LABEL 
CALL REMARKF (LABEL, IERRCNT) 

10770 FORMAT ('PD001 - ACCESS ', A8.A7,' ED=\ 14, *;') 
ASSIGN 10770 TO LABEL 
CALL REMARKF (LABEL, DN(1), DN(2), ED) 



Sample Fortran calling sequence without prefix: 

10550 FORMAT ('LOOP EXECUTED \ 14, • TIMES') 
ASSIGN 10550 TO LABEL 
CALL REMARKF (LABEL, LOOPCNT) 



IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

RERUN, NORERUN - Declares a job rerunnable/not remnnable and instruct the system to begin or 
cease monitoring jobs for functions affecting rerunnability 

SYNOPSIS 

CALL RERUN (para/n) 
CALL NORERUN (param) 

DESCRIPTION 

param One argument is required. For RERUN, if the argument is 0, the job can be rerun. If the 
argument is nonzero, the job cannot be rerun. For NORERUN, if the argument is 0, the sys- 
tem monitors for conditions causing the job to be flagged as not remnnable. If nonzero, 
such conditions are not monitored. 

RERUN declares a job remnnable or not remnnable. 

NORERUN instructs the system to begin or cease monitoring jobs for functions affecting rerunnability. 

IMPLEMENTATION 

These routines are available only to users of the COS operating system. 
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NAME 

SENSEBT - Determines whether bidirectional memory transfer is enabled or disabled 

SYNOPSIS 

CALL SENSEBT(ffKKfe) 

DESCRIPTION 

mode Transfer mode; mode has one of the following values: 

- 1 Bidirectional memory transfer is enabled 
= 0 Bidirectional memory transfer is disabled 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

SENSEFI - Determines if floating-point interrupts are permitted or prohibited 

SYNOPSIS 

CALL SENSEFI(mofe) 

DESCRIPTION 

mode Interrupt mode: 

mode=l Permit interrupts 
mode>=0 Prohibit interrupts 

IMPLEMENTATION 

This routine is available to users of both the COS and UNICOS operating systems. 
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NAME 

SETRPV - Conditionally transfers control to a specified routine 

SYNOPSIS 

CALL SETKPY(rpvcode,rpvtab,mask) 

DESCRIPTION 

rpvcode Routine to which control is transferred 
rpvtab A 40-word array reserved for system use 
mask User mask specifying reprievable conditions 

SETRPV transfers control to the specified routine when a user-selected reprievable condition occurs. 
SETRPV is called by address, 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 

SEE ALSO 

See the Macros and Opdefs Reference Manual, publication SR-0012, for details of the SETRPV parame- 
ter formats. 
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NAME 

SMACH, CMACH - Returns machine epsilon, small/large normalized numbers 

SYNOPSIS 

result-SMACH(int) 
result=CMACH(int) 

DESCRIPTION 

result Machine constant returned 

int An integer from 1 to 3. Any other value returns an error message to the logfile. For 

SMACH, int indicates that one of the following machine constants is to be returned: 

Int Constant Description 

1 .7105E-14 The machine epsilon (the smallest number 

e such that l.± e* 1), 

2 .1290E-2449 A number close to the smallest 

normalized, representable number 

3 .7750E+2450 A number close to the largest normalized, 

representable number 

For CMACH, int indicates that one of the following machine constants is to be returned: 
Int Constant Description 

1 .7105E-14 The machine epsilon (the smallest number 

e such that l.± 1). 

2 .1348E+1216 A number close to the square root of the smallest 

normalized, representable number 

3 ,7421E+1217 A number close to the square root of the largest 

normalized, representable number 

The use of CMACH(2) and CMACH(3) prevents overflow during complex division. 

These functions are calculated by Fortran versions of SMACH and CMACH (see the Basic Linear Alge- 
bra Subprograms for Fortran Usage by Chuck L. Lawson, Richard J. Hanson, Davis R. Kincaid, and 
Fred T. Crow, published by Sandia Laboratories, Albuquerque, 1977, publication number SAND77-0898). 

IMPLEMENTATION 

These routines arc availale to users of both the COS and UNICOS operating systems. 
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NAME 

SSWITCH - Tests the sense switch 

SYNOPSIS 

CALL SSmTCH(swnum,result) 

DESCRIPTION 

swnum Switch number (integer) 

result result is 1 if the switch value ranges from 1 to 6 and the switch is on. result is 2 if the 
switch value is less than 1 or greater than 6, or if the switch is off (type integer). 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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NAME 

SYSTEM - Makes requests of the operating system 

SYNOPSIS 

stotus=SYSTEM(function t arg u arg£ 

DESCRIPTION 

status Status returned in SI register (function dependent) 

function System action request number. This is the octal code of the desired system action request. 

The requests (which all begin with the characters f$) and their codes are described in the 
COS Internal Reference Manual Volume II: STP, publication SM-0141. The code is the 
jump table address (relative offset) of the function. 

argx Optional argument (required by some requests) 

org 2 Optional argument (required by some requests) 

NOTE 

Use of the SYSTEM command by other than CRI systems programmers is discouraged, as the details of 
systems request formats are subject to change. In most cases, there is a library routine which performs 
the desired functions and makes changes in request formats transparent to your program. 

IMPLEMENTATION 

This routine is available only to users of the COS operating system. 
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18. INTERFACES TO C LIBRARY ROUTINES 



A number of Fortran callable interfaces to C library routines are available under UNICOS. These rou- 
tines give a Fortran programmer access to an extensive number of routines and system calls found in 
the C library. The interfaces are simple routines which resolve calling sequence differences and pro- 
vide uppercase entry point names. Argument lists and return values should match those of the 
corresponding C routine, except where noted otherwise. Data types need to be handled as follows: 

• C character data should be defined as Fortran integer and terminated by a null (zero) byte; 'L* 
Hollerith data handles this for 1-7 characters in length. 

• C pointers should be handled by Fortran integers 

• Other C data types are compatible with their Fortran counterparts 

Interface routines should be coded as Fortran functions. 
Example: 

INTEGER FOPEN, FWRITE 
ISTREAM = FOPEN( 'filenm'L, WL ) 
IF ( ISTREAM JEQ. 0 ) THEN 

PRINT V FOPEN failed 9 

CALL ABORT 

ENDIF 

J = FWRITE( IDA(l), N, 8* ISTREAM ) 

If an argument to one of these routines is a file name, as in the above example, the name must be woid- 
aligned and terminated by a null byte. 

The following set of interface routines are provided in the standard CRAY X-MP UNICOS libraries. Refer to 
the appropriate Cray manuals for specific usage information. 
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C Library Reference Manual ( SR-0136 ) 


Purpose 


Name 


Heading 


Terminate a program and 
specify status 


exit 


exit 


Close or flush a stream 


fclose 


fclose 


Get integer file descriptor 
associated with stream 


fileno 


ferror 


Open a stream 


fopen 

fdopen 

freopen 


fopen 


Get a string from a stream 


fgets 


gets 


Put a string on a stream 


fputs 


puts 


Binary I/O 


fread 
f write 


fread 


Reposition a file pointer 
in a stream 


fseek 
ftell 


fseek 


Return value for environment 
name 


getenv 


getenv 


Get option letter from 
argument vector 


getopt 


getopt 


Make a unique file name 


mktemp 


mktemp 


Change or add value 
to the environment 


putenv 


putenv 


Create a name for a 
temporary file 


tempnam 


tempnam 



The argument list of the getenv routine differs from that of the corresponding C routine. See the man page 
in this section for the correct syntax when calling getenv from Fortran. 
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UNICOS System Calls Manual ( SR-2012 ) 



rrirposc 


INainc 


UAOninfT 

rieauinK 


Determine accessibility of 


access 


access 


a file 






Close a file descriptor 


close 


close 


Allocate storage for a file 


ialloc 


ialloc 


Move read/write file 


(seek 


lseek 


pointer 






Change data segment 
space allocation 


sbreak 
sbrk 


brk 


Provide signal control 
Fortran interface to sigctl 
Pascal interface to sigctl 


sigctl 

fsigctl 

psigctl 


sigctl 


Specify what to do upon receipt 
of a signal 

rortran interlace to signal 
rascax interlace to signal 


signal 

fsignal 
psignai 


signal 


cnange size or secondary 
oata segment 




ssDreaK 


ivcau, wnic uj 




Salxall 


secondary data segment 


ss write 




Get file status 


stat 


stat 


Get time 


time 


time 


Set and get file 


umask 


umask 


creation mark 






Get name of current operating 


uname 


uname 


system 






Remove directory entry 


unlink 


unlink 



The argument lists of the uname and time routines differ from those of the corresponding C routines. No 
arguments can be used with the Fortran call to time. See the man page in this section for the correct syntax 
when calling uname from Fortran. 

The third argument of the Fortran routines ssread and sswrite specifies the number of words to be read or 
written. This is different from the corresponding system call. The Fortran programmer should not call 
ssbreak, ssread, or sswrite in a program that accesses the SDS using the assign(l) command. 
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NAME 

getenv - Returns value for environment name 

SYNOPSIS 

INTEGER GETENV 

INTEGER value(valuesz) 

int = GETEN\(name,value f valuesz) 

DESCRIPTION 

int GETENV returns 1 if name was found in the environment and 0 if not. 

name The name of the environmental variable for which GETENV searches in the environment 
list- The name must be left-justified and terminated with a zero byte. 

value The value to which name is set, if found, in the current environment This is a character 
string, and the value variable must be big enough to handle it. 

valuesz Maximum number of words to hold string returned in value. 

IMPLEMENTATION 

This routine is available only to users of the UNICOS operating system. 

SEE ALSO 

getenv(3C) in the C Library Reference Manual, publication SR-0136 

sh(l) in the UNICOS User Commands Reference Manual, publication SR-2011 
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NAME 

GETOPT - Gets an option letter from an argument vector 
SYNOPSIS 

INTEGER FUNCTION GETOVt(options f arg) 
CHARACTERS) options 
CHARACTERS) arg 

INTEGER FUNCTION GETOVT(options t arg f argsz) 
CHARACTERS) options 
INTEGER arg(*) 
INTEGER argsz 

INTEGER GETVARG 

morearg = GETVARG(vor£,var#y2; 

INTEGER GETOARG 

morearg = GETOARG(oarg t oargsz) 

DESCRIPTION 

GETOPT returns the next option letter as the integer value of that ASCII code. For example, if the next 
option letter is a, the GETOPT returns with the value 97. If there is no next option letter, GETOPT 
returns zero. The CHAR routine can then be called to convert the integer back into a character. 

The options argument is a string of recognized option letters. If the option letter encountered does not 
match one of the letters in the options string, an error is generated. If a letter in options is followed by 
a colon, the option is expected to have an argument that may or may not be separated from it by white 
space. 

The arg argument returns the value of the argument following the option letter encountered. If arg is 
declared as a character variable, argsz need not be specified. If arg is declared as an integer array, 
argsz must be specified as the size of the array. The argument string is returned as characters packed in 
the integer array, terminated by a null byte. 

If a letter in options is followed by a semicolon (;), zero or more arguments are expected for the option. 
You must then call GETVARG to get the variable arguments until GETVARG returns 0 before the next 
call to GETOPT. 

The next variable argument is copied into the array varg (of size vargsz). GETVARG returns 0 when 
no more variable arguments exist 

After GETOPT returns 0, you can call GETOARG to get the remaining arguments from the command 
line. 

GETOARG returns 0 if there are no more arguments. The next remaining argument is copied into the 
array oarg (of size oargsz). 

If GETOPT is not used, GETOARG can be called to get the command line arguments in order, starting 
with the first argument 

EXAMPLE 

The following example shows how the options of a command might be processed using GETOPT. This 
example assumes the options a and b, which have arguments, and x and y, which do not 

CHARACTER*8 OPTIONS 
CHARACTER*80 ARGMNTS 
CHARACTER OPTLET 
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INTEGER OPTVAL 
DATA OPnONS/'a:b:xyV 

100 CONTINUE 

OPTVAL = GETOPT(OPTIONS, ARGMNTS) 
IF(OPTVAL .EQ. 0) GOTO 200 
OPTLET = CHAR(OPTVAL) 
IF (OPTLET .EQ. 'a') THEN 

* Analyze arguments from ARGMNTS 
ELSEIF (OPTLET .EQ. 'b*) THEN 

* Analyze arguments from ARGMNTS 
ELSEIF (OPTLET .EQ. V) THEN 

* Process x option 

ELSEIF (OPTLET .EQ. 'y' ) THEN 

* Process y option 
ENDIF 

200 CONTINUE 

The following example illustrates the use of GETOPT and GETOARG together. 

program test 
external getopt,getoarg 
integer getopt, getoarg 
integer arglen 
parameter (arglen=10) 
integer opt,done,argbuf(arglen) 

10 CONTINUE 

OPT = GETOPT ( 'abo: " ,ARGB UF.ARGLEN) 
IF (OPT .GT. 0) THEN 
IF (OPT .EQ. *a'R) THEN 
print '(a)' » ' option -a- present ' 

ELSEIF (OPT .EQ. 'b'R) THEN 
print '(a)' t * option -b- present ' 

ELSEIF (OPT .EQ. 'o'R) THEN 
print '(a,a8)' , ' option -o- present- \argbuf(l) 

ELSE 

C unknown option 

print '(a,a8)' , ' bad option present-\opt 
ENDIF 
GOTO 10 
ENDIF 
C all options processed. 
C 

C Get arguments 
20 CONTINUE 

DONE = GETOARG(ARGBUF,ARGLEN) 
IF(DONE .NE. 0) THEN 
print '(a,a8)' t * argument present-' ,argbuf(l) 
GO TO 20 
ENDIF 
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C done processing arguments 
end 

RETURN VALUE 

The value of GETOPT is 0 when no option characters can be found. GETOPT pints an error message 
on stderr and returns a question mark when it encounters an option letter not included in options. 
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NAME 

uname - Gets name of current operating system 
SYNOPSIS 

CALL UNAME(sysname t node name t release, version, machine) 
DESCRIPTION 

The uname routine returns information identifying the current operating system. The arguments, which 
are all of type CHARACTER, are as follows: 

sysname Current operating system name 

nodename Name by which the system is known on a communications network 

release Release of the operating system 

version Release version of the operating system 

machine Standard name identifying the hardware on which the operating system is running 

IMPLEMENTATION 

This routine is available only to users of the UNICOS operating system. 

SEE ALSO 

uname(l) in the UNICOS User Commands Reference Manual, publication SR-2011 
uname(2) in the UNICOS System Calls Reference Manual, publication SR-2012 
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19. MISCELLANEOUS UNICOS ROUTINES 



This section contains descriptions of various specialized UNICOS libraries or miscellaneous routines that 
arc not included elsewhere in this manual. 



Miscellaneous Routines and L 


ibraries 


Purpose 


Name 


Entry 


Update CRT screens 


CURSES 


CURSES 


System call interface to Fortran 


SYSCALL 


SYSCALL 


Text interface to X Window System 


XIO 


XIO 


C language X Window System Interface Library 


XLIB 


XLIB 
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NAME 



curses - Updates CRT screens 



SYNOPSIS 



#include <curses.h> 

cc [ flags ] files -lcurses [ libraries ] 



DESCRIPTION 



The curses routines give you a method of updating screens with reasonable optimization. In order to 
initialize the routines, the routine initscr() must be called before any of the other routines that deal 
with windows and screens are used. The routine endwinQ should be called before exiting. To get 
character-at-a-time input without echoing, (most interactive, screen oriented-programs want this) after 
calling initscr() you should call "nonlQ; cbreak(); noecho();" 

The fall curses interface permits manipulation of data structures called windows that can be thought of 
as two dimensional arrays of characters representing all or part of a CRT screen. A default window 
called stdscr is supplied, and others can be created with newwin. Windows are referred to by variables 
declared WINDOW*, the type WINDOW* is defined in curses.h to be a C structure. These data struc- 
tures are manipulated with functions described below, among which the most basic are move, and 
addch, (More general versions of these functions are included with names beginning with *w\ allow- 
ing you to specify a window. The routines not beginning with *w' affect stdscr.) Then refreshQ is 
called, telling the routines to make the user's CRT screen look like stdscr. 

Mini-Curses is a subset of curses that does not allow manipulation of more than one window. To 
invoke this subset, use -DMINICURSES as a cc option. This level is smaller and faster than full curses. 

If the environment variable TERMINFO is defined, any program using curses checks for a local termi- 
nal definition before checking in the standard place. For example, if the standard place is 
/usr/lib/terminfo, and TERM is set to vtlOO, then normally the compiled file is found in 
/usr/lib/terminfo/v/vtlOO. (The v is copied from the first letter of vtlOO to avoid creation of huge 
directories.) However, if TERMINFO is set to /usr/mark/myterms, curses first checks 
/opusr/mark/myterms/v/vtlOO, and if that fails, checks /usr/lib/terminfo/v/vtlOO. This is useful for 
developing experimental definitions or when write permission in /usr/lib/terminfo is not available. 



Routines listed here may be called when using the full curses. Those marked with an asterisk may be 
called when using Mini-Curses. 



FUNCTIONS 



box(win, vert, hor) 



Routine 
addch(cA)* 



addstr(rtr)* 

attroff(^rj)* 

attron(attrs)* 

attrset(attr.y)* 

baudrateQ* 

beepO* 



Description 

Adds a character to stdscr 
(like putchar) (wraps to next 
line at end of line) 

Calls addch with each character in str 

Turns off attributes named 

Turns on attributes named 

Sets current attributes to attrs 

Current terminal speed 

Sounds beep on terminal 

Draws a box around edges of win 

vert and hor are characters to use for vertical 

and horizontal edges of box 
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Routine 
clear() 

clearok(uwi, bf) 

clrtobot( ) 

eIrtoeoI( ) 

cbreak()* 

delay_putput(ms)* 

delch() 

deleteln() 

delwin(w//t) 

doupdate() 

echo()* 

endwin()* 

eraseQ 

erasechar() 

fixterm() 

flash () 

flushinpO* 

getchQ* 

getstr(tfr) 

gettmode() 

getyx(win t y, x) 

has_ic() 

has_il() 

idlokOvm, bf)* 

inch() 

initscrQ* 

insch(c) 

insertln() 

intrflush(\wi, bj) 

keypadCwin, bf) 
killchar() 
leaveok(wm, flag) 



Iongname() 
meta(nwi, jlag)* 
move(y, x)* 
mvaddch(y, x, ch) 
mvaddstr(y» x> sir) 

mvcwr{oldrow t oldcol, newrow, newcol) 



Description 
Clears stdscr 

Clears screen before next redraw of win 
Clears to bottom of stdscr 
Clears to end of line on stdscr 
Sets cbreak mode 

Inserts ms millisecond pause in output 
Deletes a character 
Deletes a line 
Deletes win 

Updates screen from all wnooutrefresh 

Sets echo mode 
Ends window modes 
Erases stdscr 

Returns user's erase character 

Restores tty to "in curses" state 

Flashs screen or beep 

Throws away any typeahead 

Gets a character from tty 

Gets a string through stdscr 

Establishes current tty modes 

Gets (y, x) co-ordinates 

True if terminal can do insert character 

True if terminal can do insert line 

Uses terminal's insert/delete line if bf != 0 

Gets char at current (y, *) co-ordinates 

Initializes screens 

Inserts a character 

Inserts a line 

Interrupts flush output if bf 
is TRUE 

Enables keypad input 

Returns current user's kill character 

OK to leave cursor anywhere after refresh if 

flagl=0 for win, otherwise cursor must be left 

at current position. 

Returns verbose name of terminal 

Allows meta characters on input if flag != 0 

Moves to (y, *) on stdscr 

Move(y, x) then addch(cA) 

similar... 



Low level cursor motion 
mvdelch(y, x) like delch, but move(y, x) first 

mvgetch(y, x) etc. 
mvgetstr(y, x) 
mvinch(y, x) 
mvinsch(y, x $ c) 
mvprintw(y, x t fint> args) 
ravscanw(y, x,fmt, args) 
mvwaddch(wM, y, x, ch) 
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Routine Description 
mvwaddstrOwn, y, x, str) 
mvwdelch(vvi/i, y t x) 
mvwgetch(wi«, y, x) 
mvwgetstrOvw, y> x) 
mvwin(w//i, by, bx) 
mywmch(win, y, x) 
mvwmschiwin, y,x, c) 
mvwprintwOvm, y, x, fmt, args) 
mvwscanw(w//j, y t x,fmt t args) 
newpad(n/M6?, ncols) 
newterm(fyp^ , fd) 

newwin(lines, cols, beginjy, begin_x) 

mo* 

nocbr eak( )* 
nodeIay(w/*, bf) 
noechoO* 
nonl()* 
norawQ* 

overlay (winl, wiriZ) 
overwrite(w7wi, win2) 
pnoutrefresh(pa£/, pminrow, pmincol, sminrow, 
smincol, smaxrow, smaxcol) 

Like prefresh but with no output until doupdate called 

prefiresh(pa<i» pminrow, pmincol, sminrow, 
smincoi smaxrow, smaxcol) 

Refreshes from pad starting with given upper left 
corner of pad with output to given 
portion of screen 



Creates a new pad with given dimensions 

Sets up new terminal of given type to output on fd 

Creates a new window 
Sets newline mapping 
Unsets cbreak mode 

Enables nodelay input mode through getch 

Unsets echo mode 

Unsets newline mapping 

Unsets raw mode 

Overlays winl on winl 

Overwrites winl on top of win2 



printw(/mr, argl, arg2, ...) 

raw()* 

refresh()* 

resetterm( )* 

resettyO* 

savetermQ* 

savettyQ* 

scanw(/"mf, argl, arg2 t ..J 

scroll(ivm) 
scroIlok(wm f flag) 
set_term(*£w) 
setscrreg(f, b) 
setterm(rypi) 

setupterm(te/7n, filenum t errret) 

standend()* 

standout()* 

subwin(uwi, lines, cols, begin_y t beginjc) 



Does printf on stdscr 
Sets raw mode 

Makes current screen look like stdscr 
Sets tty modes to "out of curses" state 
Resets tty flags to stored value 
Saves current modes as "in curses" state 
Stores current tty flags 

Does scanf through stdscr 

Scrolls win one line 

Allows terminal to scroll if flag != 0 

Now talk to terminal new 

Sets user scrolling region to lines t through b 

Establishes terminal with given type 

Clears standout mode attribute 
Sets standout mode attribute 

Creates a subwindow 
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Routine 


Description 


touchwin(wm) 


Changes all of win 


traceoffQ 


Turns off debugging trace output 


traceon( ) 


Turns on debugging trace output 


typeahead(fd) 


Use file descriptor /d to check typeahead 


unctrl(c/i)* 


Printable version of ch 


waddchOvin, ck) 


Adds character to win 


waddstr(W/i, sir) 


Adds string to win 


wattroff(wm ( attrs) 


Turns off atfr.y in win 


wattron(H>m, attrs) 


Turns on artrs in win 


wattrset(mn, attrs) 


Sets ewrj in to attrs 


wclear(wzn) 


Clears win 


wclrtobot(win) 


Clears to bottom of win 


wdrtoeol(ww) 


Clears to end of line on win 


wdelch(wm, c) 


Deletes character from win 


wdeleteln(wm) 


Deletes line from win 


werase(win) 


Erases win 


wgetehOvm) 


Gets a character through win 


wgetstr(wm, str) 


Gets a string through win 


winch(wi/i) 


Gets character at current (y t x) in win 


winsch(vv/n, c) 


Inserts character into win 


winsertln(wz>z) 


Inserts line into win 


wmove(wi/i, >, x) 


Sets current (y, x) co-ordinates on win 


wnoutrefresh(wm) 


Refreshes but no screen output 


wprintw(ww ( ./m/, argl, arg2, ...) 






Does printf on win 


wrefresh(n'/n) 


Makes screen look like win 


wseanw(wm, fint, argl, argl, ...) 






Do scanf through win 


wsetscrreg(wm, f, 6) 


Sets scrolling region of win 


wstandendOvm) 


Clears standout attribute in win 


wstandout(wi>i) 


Sets standout attribute in win 



TERMINFO LEVEL ROUTINES 



These routines should be called by programs wishing to deal directly with the terminfo database. Due 
to the low level of this interface, use of them is discouraged. Initially, setupterm should be called. 
This defines the set of terminal dependent variables defined in terminfo(4F). The include files 
<curses.h> and <term.h> should be included to get the definitions for these strings, numbers, and flags. 
Parmeterized strings should be passed through tparm to instantiate them. All terminfo strings (includ- 
ing the output of tparm) should be printed with tputs or putp. Before exiting, resetterm should be 
called to restore the tty modes. (Programs desiring shell escapes or suspending with control Z can call 
resetterm before the shell is called and fixterm after returning from the shell.) 



Routine Description 
fixterm() Restores tty modes for terminfo use 

(called by setupterm) 

resettermQ Resets tty modes to state before program entry 
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Routine 

settipterm(/irm, fd, rc) 



tparm(rfr, pi, p2, p9) 
tputs(tfr, affcnt, putc) 



putp(rfr) 

\idpuis(attrs, putc) 



v\&2&tr(attrs) 



Description 

Reads in database. Terminal type is the 
character string term, all output is to UNCOS 
System file descriptor fd. A status value is 
returned in the integer pointed to by rc: 1 
is normal. The simplest call would be 
setupterm(0, 1, 0) which uses all defaults. 

Instantiates string str with parameters p.. 
Applies padding information to string str. 
affcnt is the number of lines affected, 
or 1 if not applicable. Putc is a 
putchar-likc function to which the characters 
are passed, one at a time. 
Calls tputs 
(str, 1 1 putchar) 

Outputs the string to put terminal in video 
attribute mode attrs, which is any 
combination of the attributes listed below. 
Characters are passed to putchar-like 
function putc. 

Like vidputs but outputs through 
putchar 



TERMCAP COMPATIBILITY ROUTINES 

These routines were included as a conversion aid for programs that use termcap. Their parameters are 
the same as for termcap. They are emulated using the terminfo database. They may go away at a 
later date. 



Routine 

tgetent(6p, name) 
tgetflag(id) 
tgetnum(td) 
tgetstr(id, area) 
tgotoCcap, cot, row) 
tputs(cap, affcnt, fn) 



Description 

Looks up termcap entry for name 

Gets Boolean entry for id 

Gets numeric entry for id 

Gets string entry for id 

Applies parameters to given cap 

Applies padding to cap calling fn as putchar 



ATTRIBUTES 



The following video attributes can be passed to the functions attron,attroff,attrset 



Attribute 

AJSTANDOUT 

ASUNDER LINE 

AJREVERSE 

A_BLINK 

AJMM 

A_BOLD 

AJBLANK 

AJ>ROTECT 

A ALTCHARSET 



Description 

Terminal's best highlighting mode 

Underlining 

Reverse video 

Blinking 

Half bright 

Extra bright or bold 

Blanking (invisible) 

Protected 

Alternate character set 
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FUNCTION KEYS 

The following function keys might be returned by getch if keypad has been enabled Note that not all 
of these are currently supported, due to lack of definitions in terminfo or the terminal not transmitting a 
unique code when the key is pressed. 



Name 


Value 


Key name 


KEY_BREAK 


0401 


Break key (unreliable) 


KEY_DOWN 


0402 


The four arrow keys ... 


KEY_UP 


0403 




KEY_LEFT 


0404 




KEY_RIGHT 


0405 




KEY_HOME 


0406 


Home key (upward+left arrow) 


KEY_BACKSPACE 


0407 


Backspace (unreliable) 


KEY.FO 


0410 


Function keys. Space for 64 is reserved. 


KEY_F(n) 


(KEY_FO+(n)) Formula for/n. 


KEY_DL 


0510 


Delete line 


KEYJL 


0511 


Insert line 


KEY_DC 


0512 


Delete character 


KEY_IC 


0513 


Insert character or enter insert mode 


KEYJEIC 


0514 


Exit insert character mode 


KEY_CLEAR 


0515 


Clear screen 


KEY_EOS 


0516 


Clear to end of screen 


KEY_EOL 


0517 


Clear to end of line 


KEY__SF 


0520 


Scroll 1 line forward 


KEY_SR 


0521 


Scroll 1 line backwards (reverse) 


KEY_NPAGE 


0522 


Next page 


KEY_PPAGE 


0523 


Previous page 


KEY_STAB 


0524 


Set tab 


KEY_CTAB 


0525 


Clear tab 


KEY_CATAB 


0526 


Clear all tabs 


KEY_ENTER 


0527 


Enter or send (unreliable) 


KEY_SRESET 


0530 


Soft (partial) reset (unreliable) 


KEY_RESET 


0531 


Reset or hard reset (unreliable) 


KEY_PRINT 


0532 


Print or copy 


KEY_LL 


0533 


Home down or bottom (lower left) 



IMPLEMENTATION 

These routines are available only to users of the UNICOS operating system. 

SEE ALSO 

terminfo(4F) in the UNICOS File Formats and Special Files Reference Manual, publication SR-2014 
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NAME 



xio - Text interface to the X Window System 



Display * 

xstart (program, disp, evfunc) 
char ^program; 
char *disp; 
int (*evfunc)(); 
TEXT * 

xopen(prompt ? geom) 
char *prompt; 
char *geom; 
xclose(win) 
TEXT *win; 
TEXT * 
xtitleCpwin) 
TEXT *pwin; 

xprintf(win, format [ , arg ] ♦..) 

TEXT *win; 

char ^format; 

xputc(c, win) 

TEXT *win; 

char c; 

xputs(s, win) 

TEXT *win; 

char *s; 

xflush(win) 

TEXT *win; 

xeventsO 

xselect(win, mask) 
TEXT *win; 
long mask; 
xunselect(win, mask) 
TEXT *win; 
long mask; 

xconfigure(win, nw» nh, xw, xh) 

TEXT *win; 

int nw, nh, xw, xh; 

Window 

xfindwindow(prompt) 
int (*prompt)0; 



These functions provide a standard I/O like interface to the X Window System to a single display. The 
xstart routine is used initialize the display, program is used to extract the following variables from 
'/^defaults: 



SYNOPSIS 



DESCRIPTION 



BodyFont 
ReverseVideo 



BorderWidth 



Foreground 



Background 



Border 
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If disp is nonzero, it refers to the display name. If it is zero then the environment varaiable DISPLAY is 
used as the display name. The evfunc is used by the xevent function (see below), xstart returns non 
zero if the contact is made with the display. 

The xopen routine is used to open a new window on the display started by xstart The geom argument 
specifies a standard X geometry (Le =width x height + xoff + yoff). xopen returns a non null TEXT 
pointer if it succeeds* 

xclose closes and destroys the window refered to by win 

xtitle returns a TEXT pointer to a one line title subwindow contained in the window pwin. It is a vio- 
lation to open a title in a title or try to open more than one title in a window. 

xprintf, xputc, xputs, and xflush work as their stdio counterparts fprintf, fputc, fjputs, and fflush. 

xevents handles X events and calls evfunc from above for any event it does not know how to deal 
with. It passes evfunc a pointer to the XEvent structure. This routine must be called whenever there is 
input waiting on the file descriptor associated with X (dpynoO in C will return the file descriptor). 

xselect allows the selection of more events on the TEXT window. 

xunseletc allows the deselections of events selected via xselect. 

xconfigure sets a minimum and maximum size for the TEXT window. Setting any value to 0 will 
remove the limit for that value. 

xfindwindow grabs the server, makes the mouse a target, calls the prompt routine (which should ask 
the user to select a window) and returns the window ID of the window selected. 

IMPLEMENTATION 

These routines are available only to users of the UNICOS operating system. 

SEE ALSO 

Complete documentation for the text interface to the X Window System, is in the Xlib - C Language X 
Interface Protocol Version 10 by Jim Gettys and Tony Delia Fera of the Digital Equipment Corporation, 
and Ron Newman of the Massachusetts Institute of Technology. 

NOTE 

The X Window System is a trademark of MIT. 
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NAME 

Xlib - C Language X Window System Interface Library 

SYNOPSIS 

include <X/Xlib.h> 

DESCRIPTION 

This library is the low level interface for C to the X protocol, which supports the X Window System, X 
Version 10, January 1986, from M.I.T. At present, the X Window System comprises more than 150 
subroutines. 

This library gives complete access to all capability provided by the X Window System (protocol version 
10), and is intended to be the basis for other higher level libraries for use with X. 

FILES 

/usr/include/X/Xlib.h, /usr/lib/libX.a 

IMPLEMENTATION 

This library is available only to users of the UNTCOS operating system. 

SEE ALSO 

Complete documentation for the C language interface to the X Window System, is in the Xlib - C 
Language X Interface Protocol Version 10 by Jim Gettys and Tony Delia Fera of the Digital Equipment 
Corporation, and Ron Newman of the Massachusetts Institute of Technology. 
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$OUT from register copy - SNAP 16-13 

32 bits from 64 bits write - WRTITBM 12-82 

32-bit words write - WRTTIBM 12-82 

60-bit integer - INT6460 8-14 

60-bit integer to 64-bit integer conversion - 

INT6064 843 

60-bit pack and unpack - P6460 9-4 

60-bit single-precision to 64-bit single 

precision conversion - FP6064 8-12 

64 bit integer divide - LDIV 2*51 

64-bit complex conversion - VXZCTC 8-36 

64-bit D format to single-precision 

conversion - VXDCTC 8-27 

64-bit integer divide - LDIV 2-51 

64-bit integer to 60-bit integer conversion - 

INT6460 8-14 

64-bit integer to VAX LNTEGER*2 conversion - 

VXICn 8-32 

64-bit single-precision - USSCTI 8-26 

64-bit single-precision - VXDCTI 8-28 

64-bit single-precision - VXGCTI 8-30 

64-bit single-precision - VXSCTI 8-35 

ABORT - Requests abort with traceback. 17-5 

abort job - ABORT - ...17-5 

abort job - ERREX1T 17-20 

abort NAMEUST job - RNLSKIP 12-56 

ABS - Computes absolute value 2-7 

absolute value - ABS 2-7 

absolute value - ISAM AX 6-1 1 

absolute value - ISMAX 6-12 

absolute value - SASUM 4-101 

absolute value of a complex vector - ISAMAX... 6-1 1 

absolute value of a real vector - ISAMAX 6-11 

absolute values of vector elements addition - 

SASUM 4-101 

accept data - ACPTBAD 12-9 

access test - IFDNT. 3-7 

ACOS - Computes arccosine 2-9 

acos - Computes arccosine 2-9 

ACPTBAD - Makes bad data available 12-9 

active subroutine list - TRBK 16-20 

ACTTABLE - Returns the Job Accounting Table 

(JAT) 17-6 

add characters for NAMEUST - RNL 12-54 

add memory - MEMORY 17-35 

add to LFT - ADDLFT 3-4 

add word to table - TMADW 1 1-13 

addition (double-precision) - DBLJPREC 2-37 

addition (triple-precision) - TADD 2-84 

ADDLFT - Adds a name to the Logical File 

Table (LFT) 3-4 

Adds a name to the Logical File Table (LFT) - 

ADDLFT 3-4 

Adds a scalar multiple of a real or complex 

vector -SAXPY 4-102 

Adds a word to a table - TMADW 1 1-13 

Adds entries to the multitasking history 

trace buffer - BUFUSER 14-13 
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Adds or deletes characters from the set of 

characters recognized by the NAMELIST - 



RNL 12-54 

adjust heap block - HPNEWLEN 11-9 

A1MAG - Computes imaginary portion of a 

complex number. 2-1 1 

AINT - Computes real and double-precision 

truncation 2-12 

allocate memory from heap - HPALLOC 11-4 

allocate table space - TMATS 11-15 

allocated heap block change - HPNEWLEN 11-9 

Allocates a block of memory from the heap - 

HPALLOC 11-4 

Allocates table space - TMATS 11-15 

Allows a job to communicate with another job 

- IJCOM 17-28 

Allows a job to suspend itself until selected 

events occur - ERECALL.. 17-18 

Allows a program to access datasets in the 

System Directory - SDACCESS 3-8 

Allows an index to be used as the current 

index -STTNDX 12-63 

Allows each NAMELIST variable to begin on a 

new line - WNLL1NE 12-74 

Allows special processing at 

beginning-of-volume -PROCBOV.. 12-44 

ALOG - Computes natural logarithm 2-13 

ALOG10 - Computes common logarithm 2-15 

AMAXO - Returns the largest of all arguments 6-18 

AMAX1 - Returns the largest of all arguments 6-18 

AMINO - Returns the smallest of all arguments 6-19 

AMIN1 - Returns the smallest of all arguments 6-19 

AMOD - Computes remainder of xl/x2 2-56 

AND - Computes logical product 2-17 

ANINT - Finds nearest whole number 2-19 

Applies a complex Fast Fourier Transform 

(FFT) - CFFT2 5-3 

Applies a complex-to-real Fast Fourier 

Transform (FFT) - CRFFT2 5-6 

Applies a modified Givens plane rotation - 

SROTM 4-124 

Applies a real-to-complex Fast Fourier 

Transform (FFT) - RCFFT2 5-7 

Applies an orthogonal plane rotation - SROT 4-121 

Applies complex-to-complex Fast Fourier 

Transforms (FFT) on multiple input vectors 

- CFFTMLT 5-4 

Applies complex-to-real and real -to-complex 

Fast Fourier Transforms (FFT) on 

multiple input vectors - RFFTMLT 5-8 

Applies the complex plane rotation computed 

byCROTG-CROT 4-40 

approximate double-precision value - SNGLR .2-81 

APUTWA - Writes to a word-addressable, 

random-access dataset 1 2-46 

AQCLOSE - Closes an asynchronous queued I/O 

dataset or file 12-11 

AQIO dataset close - AQCLOSE 12-1 1 

AQIO dataset open - AQOPEN 12-12 

AQIO dataset open - AQOPENDV 12-13 

AQIO request stop - AQSTOP 12-20 

AQIO status - AQSTAT 12-19 

AQIO wait - AQWATT 12-21 

AQIO write - AQWRTTE 12-22 
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AQOPEN - Opens a dataset or file for 

asynchronous queued I/O , 12-12 

AQOPENDV - Opens a dataset or file for 

asynchronous queued I/O, allowing user to 

specify dataset size and physical location.. 12-13 

AQREAD - Queues a simple or compound 

asynchronous I/O read request..,.. 12-15 

AQREADC - Queues a simple or compound 

asynchronous I/O read request 12-15 

AQREADCI - Queues a simple or compound 

asynchronous I/O read request... .. 12-15 

AQREADI - Queues a simple or compound 

asynchronous I/O read request 12-15 

AQRECALL - Delays program execution during a 

queued I/O sequence 12-17 

AQRIR - Delays program execution during a 

queued I/O sequence 12-17 

AQSTAT - Checks the status of asynchronous 

queued I/O requests 12-19 

AQSTOP - Stops the processing of asynchronous 

queued VO requests ...,12-20 

AQWAIT - Waits on a completion of 

asynchronous queued I/O requests 12-21 

AQWRITE - Queues a simple or compound 

asynchronous I/O write 12-22 

AQWRITEC - Queues a simple or compound 

asynchronous I/O write 12-22 

AQWRTTEI - Queues a simple or compound 

asynchronous I/O write 12-22 

AQWRTECI - Queues a simple or compound 

asynchronous I/O write ...12-22 

arbitrary increments - MXMA 4-88 

arbitrary increments - MXVA 4-94 

arccosine - ACOS 2-9 

arcsine - ASIN 2-20 

arctangent - ATAN 2-22 

arctangent - ATAN2 2-24 

argument - GETARG ..17-22 

argument - IARGC 17-26 

argument vector -GETOPT 18-5 

array byte or bit move - MOV 10-5 

array byte replace - BYT 10-2 

array comparison - KOMSTR 10-4 

array search - FINDCH 10-3 

array search - ISRCHEQ 6-13 

array search - ISRCHFLT 6-14 

array search - ISRCHILT 6-15 

array search - ISRCHMEQ 6-16 

array search - ISRCHMLT ...6-17 

array search - WHENEQ 6-22 

ASCDC - Converts CDC display code character 

to ASCII character and vice versa 8-1 1 

ASCII conversion - DSASC 8-1 1 

ASCII from binary conversion - B20CT 8-5 

ASCH from time - TSDT ....15-10 

ASCE to EBCDIC conversion - USCCTC. 8-18 

ASCII to integer conversion - CHCONV 8-10 

ASCII to time-stamp conversion - DTTS 15-5 

ASCII translation - TR 8-16 

ASIN - Computes arcsine 2-20 

asin - Computes arcsine 2-20 

assign a multitasking lock - LOCKASGN 14-21 

assign multitasking barrier - BARASGN 14-5 

assign variable - BARASGN 14-5 

assign variable as a lock - LOCKASGN 14-21 



assign variable to an event - EVASGN 14-14 

AS YNCDR - Set I/O mode for random access 

routines to asynchronous * ..... 12-24 

asynchronous I/O - AQOPENDV 12-13 

asynchronous I/O - AQOPEN ...12-12 

asynchronous I/O status check - CHECKMS 12-25 

asynchronous I/O stop - AQSTOP 12-20 

asynchronous I/O wait - AQWATT.... 12-21 

asynchronous I/O wait - WAITMS 12-69 

asynchronous mode - ASYNCMS 12-24 

asynchronous read - AQREAD 12-15 

asynchronous read - GETWA 12-38 

asynchronous read - GETWAU 12-40 

asynchronous status - AQSTAT 12-19 

asynchronous write - AQWRITE ..12-22 

Asynchronously reads a number of words from 

the disk, directly to user - GETWAU 12-40 

ASYNCMS - Set I/O mode for random access 

routines to asynchronous 12-24 

ATAN - Computes arctangent for single argument .2-22 

atan - Computes arctangent for single argument 2-22 

ATAN2 - Computes arctangent for two arguments 2-24 

atan2 - Computes arctangent for two arguments .....2-24 

attributes (video) - CURSES 19-2 

B0 write -FXP 16-6 

B20CT - Places an octal ASCII representation 

of a Cray word into a character area 8-5 

BACKFILE - Positions a dataset after the 

previous EOF 13-3 

bad data - ACPTBAD 12-9 

bad data skip - SKIPBAD 12-61 

banded symmetric systems of linear equations 

- EISPACK. 4-65 

BARASGN - Identifies an integer variable to 

use as a barrier 14-5 

BARREL - Releases the identifier assigned to 

a barrier 14-6 

barrier - BARASGN 14-5 

barrier -BARREL 14-6 

barrier synchronization with tasks - BARSYNC ...14-7 

BARS YNC - Registers the arrival of a task at 

a barrier 14-7 

Basic Linear Algebra Subprogram (CRI 

extension) - CGEMMS 4-15 

Basic Linear Algebra Subprogram (CRI 

extension) - SGEMMS 4-1 10 

Basic Linear Algebra Subprogram - CGBMV 4-10 

Basic Linear Algebra Subprogram - CGEMM 4-13 

Basic Linear Algebra Subprogram - CGEMV 4-18 

Basic Linear Algebra Subprogram - CGERC. „,.„4-20 

Basic Linear Algebra Subprogram - CGERU .....4-22 

Basic Linear Algebra Subprogram - CHBMV 4-24 

Basic Linear Algebra Subprogram - CHEMM .4-26 

Basic Linear Algebra Subprogram - CHEMV 4-29 

Basic Linear Algebra Subprogram - CHER 4-31 

Basic Linear Algebra Subprogram - CHER2 .4-33 

Basic Linear Algebra Subprogram - CHER2K 4-35 

Basic Linear Algebra Subprogram - CHERK 4-38 

Basic Linear Algebra Subprogram - CROT 4-40 

Basic Linear Algebra Subprogram - CROTG 4^tl 

Basic Linear Algebra Subprogram - CS YMM 4-42 

Basic Linear Algebra Subprogram - CSYR2K 4-45 

Basic Linear Algebra Subprogram * CSYRK 4-48 

Basic Linear Algebra Subprogram - CTBM V 4-50 
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Basic Linear Algebra Subprogram - CTBSV 4-53 

Basic Linear Algebra Subprogram - CTRMM 4-56 

Basic Linear Algebra Subprogram - CTRMV 4-58 

Basic Linear Algebra Subprogram - CTRSM 4-60 

Basic Linear Algebra Subprogram - CTRSV 4-62 

Basic Linear Algebra Subprogram - DOT 4-64 

Basic Linear Algebra Subprogram - INTRO 4-1 

Basic Linear Algebra Subprogram - SASUM 4-101 

Basic Linear Algebra Subprogram - SAXPY 4-102 

Basic Linear Algebra Subprogram - SCAL 4-103 

Basic Linear Algebra Subprogram - SCOPY 4-105 

Basic Linear Algebra Subprogram - SGBMV 4-106 

Basic Linear Algebra Subprogram - SGEMM.... 4-108 

Basic Linear Algebra Subprogram - SGEMV 4-113 

Basic Linear Algebra Subprogram - SGER , 4-1 14 

Basic Linear Algebra Subprogram - SMXPY 4-115 

Basic Linear Algebra Subprogram - SNRM2 4-116 

Basic Linear Algebra Subprogram - SPDOT 4-120 

Basic Linear Algebra Subprogram - SROT , 4-121 

Basic Linear Algebra Subprogram - SROTG 4-122 

Basic Linear Algebra Subprogram - SROTM ..... ....4-124 

Basic Linear Algebra Subprogram - SROTMG 4-126 

Basic Linear Algebra Subprogram - SSBMV 4-131 

Basic Linear Algebra Subprogram - SSUM 4-133 

Basic Linear Algebra Subprogram - SSWAP 4-134 

Basic Linear Algebra Subprogram - SSYMM.— 4-135 

Basic Linear Algebra Subprogram - SSYMV 4-138 

Basic Linear Algebra Subprogram - SS YR 4-139 

Basic Linear Algebra Subprogram - SS YR2 4-140 

Basic Linear Algebra Subprogram - SSYR2K 4-141 

Basic Linear Algebra Subprogram - SSYRK 4-144 

Basic Linear Algebra Subprogram - STBMV 4-146 

Basic Linear Algebra Subprogram - STBSV..... 4-148 

Basic Linear Algebra Subprogram - STRMM 4-150 

Basic Linear Algebra Subprogram - STRMV 4-152 

Basic Linear Algebra Subprogram - STRSM 4-153 

Basic Linear Algebra Subprogram - STRSV 4-155 

Basic Linear Algebra Subprogram - SXMPY 4-156 

beginning-of-volume processing - CLOSE V 12-27 

beginning-of -volume processing - PROCBOV 12-44 

beginning-of-volume processing - STARTSP 12-62 

Begins special processing at end-of-volume 

(EOV) (obsolete) - PROCEOV 12-45 



Begins user EOV and BOV processing - CLOSEV 12-27 

Begins user EOV and BOV processing - STARTSP 12-62 



BICONV - Converts a specified integer to a 
decimal ASCII string representing the 

integer 8-6 

BICONZ - Converts a specified integer to a 
decimal ASCII string representing the 

integer 8-6 

bidirectional memory test - SENSEBT 17-43 

bidirectional memory transfer - CLEARBT 17-9 

bidirectional memory transfer - CLEARBTS 17-10 

binary to character conversion - B20CT 8-5 

binary to octal conversion - B20CT ....8-5 

bit mask - MASK 2-55 

bit move -MOV 10-5 

bit population parity - POPPAR 2-64 

bit shift - SHIFTL 2-72 

bit shift - SHIFTR 2-74 

blanks for value - FSUP 12-33 

BLAS - CROT 4-40 

BLAS - CROTG .4-41 

BLAS - DOT 4-64 



BLAS -INTRO 4-1 

BLAS - SASUM 4-101 

BLAS -SAXPY 4-102 

BLAS - SCAL 4403 

BLAS -SCOPY 4-105 

BLAS -SMXPY 4-115 

BLAS - SNRM2 4-116 

BLAS - SPDOT 4-120 

BLAS - SROT 4-121 

BLAS - SROTG.... 4-122 

BLAS -SROTM 4-124 

BLAS - SROTMG 4-126 

BLAS - SSUM .4-133 

BLAS - SSWAP 4-134 

BLAS -SXMPY 4-156 

BLAS 2 - CGBM V 4-10 

BLAS 2 - CGEMV .4-18 

BLAS 2 - CGERC .4-20 

BLAS 2 - CGERU 4-22 

BLAS 2 - CHBMV 4-24 

BLAS 2 - CHEMV 4-29 

BLAS 2 -CHER .4-31 

BLAS 2 - CHER2 .4-33 

BLAS 2 - CTBMV 4-50 

BLAS 2 -CTBSV 4-53 

BLAS 2 - CTRMV 4-58 

BLAS 2 -CTRSV 4-62 

BLAS 2 -INTRO 4-1 

BLAS 2 - SGBMV. .4-106 

BLAS 2 -SGEMV ..4-113 

BLAS 2 -SGER 4-114 

BLAS 2 - SSBMV ...4-131 

BLAS 2 -SSYMV 4-138 

BLAS 2 - SSYR 4-139 

BLAS 2 - SSYR2 4-140 

BLAS 2 - STBMV 4-146 

BLAS 2 - STBS V 4-148 

BLAS 2 -STRMV 4-152 

BLAS 2 - STRSV 4-155 

BLAS 3 (CRI extension) - CGEMMS 4-15 

BLAS 3 (CRI extension) - SGEMMS 4-110 

BLAS 3 - CGEMM .4-13 

BLAS 3 - CHEMM 4-26 

BLAS 3 - CHER2K 4-35 

BLAS 3 - CHERK 4-38 

BLAS 3 - CSYMM .4-42 

BLAS 3 -CSYR2K 4-45 

BLAS3-CSYRK 4-48 

BLAS 3 -CTRMM 4-56 

BLAS 3 -CTRSM 4-60 

BLAS 3 - INTRO 4-1 

BLAS 3 - SGEMM 4-108 

BLAS 3 - SSYMM 4-135 

BLAS 3 - SSYR2K 4-141 

BLAS 3 -SSYRK 4-144 

BLAS 3 - STRMM 4-150 

BLAS 3 - STRSM 4-153 

block extend or copy - HPCLMOVE 1 1-6 

block heap change - HPNEWLEN 11-9 

block length heap - IHPLEN 1 1-1 1 

block of memory to heap - HPDEALLC 1 1-7 

block tape position - SETTP 12-59 

blocks in dataset - NUMBLKS 13-9 

Boolean -AND 2-17 

Boolean - COMPL .2-29 



SR-0113 Index-3 D 



Boolean - EQV 2-44 

Boolean - LEADZ. 2-52 

Boolean - MASK 2-55 

Boolean -NEQV 2-58 

Boolean -OR 2-61 

Boolean - POPCNT 2-63 

Boolean - POPPAR 2-64 

Boolean - SHIFT 2-70 

Boolean - SHIFTL 2-72 

Boolean - SfflFTR 2-74 

BOV processing - CLOSEV 12-27 

BOV processing - PROCBOV 12-44 

BOV processing - S VOLPRC 12 65 

BUFDUMP - Unformatted dump of multitasking 

history trace buffer .....14-8 

buffer record into - HNDMS 12-32 

BUFPRINT - Formatted dump of multitasking 

history trace buffer 14-9 

BUFTUNE - Tune parameters controlling 

multitasking history trace 14-10 

BUFUSER - Adds entries to the multitasking 

history trace buffer..... 14-13 

bypass file - SKIPR 13-11 

bypass records - SKIPR 13-11 

byte and bit manipulation routines 

introduction - INTRO 104 

byte comparison - KOMSTR 10-4 

byte move - MOV 10-5 

byte replacement - BYT. 10-2 

C Language X Window System Interface Library 

-XLIB 19-10 

C library for X Window System - XLIB 19-10 

C snapshot dump - SYMDUMP 16-16 

CABS - Computes absolute value ..2-7 

call tracing - SETPLIMQ 16-12 

CALLCSP - Executes a COS control statement 3-5 

caller name - GETNAMEQ 16-7 

calling sequence information - TRBKLVL 16-21 

calling sequence list - TRBK 16-20 

CAXPY - Adds a scalar multiple of a real or 

complex vector 4-102 

CCOP Y - Copies a real or complex vector into 

another vector 4-105 

CCOS - Computes cosine 2-32 

CCS - Cracks a control statement 17-7 

CDC 60-bit integer conversion - INT6064 8-13 

CDC 60-bit single-precision conversion - 

FP6064 8-12 

CDC display code characters - DSASC 8-1 1 

CDC to ASCII character conversion - DSASC 8-1 1 

CDOTC - Computes a dot product (inner 

product) of two real or complex vectors 4-64 

CDOTU - Computes a dot product (inner 

product) of two real or complex vectors 4-64 

CEXP - Computes exponential function 2-46 

CEXPR - Cracks an expression 17-8 

CFFT2 - Applies a complex Fast Fourier 

Transform (FFT) 5-3 

CFFTMLT - Applies complex-to-complex Fast 

Fourier Transforms (FFT) on multiple 

input vectors 5-4 

CGBMV - Multiplies a complex vector by a 

complex general band matrix 4-10 



CGEMM - Multiplies a complex general matrix 

by a complex general matrix 4-13 

CGEMM S - Multiplies a complex general matrix 

by a complex general matrix using 

Strassen's algorithm .4-15 

CGEMV - Multiplies a complex vector by a 

complex general matrix 4-18 

CGERC - Performs conjugated rank 1 update of 

a complex general matrix 4-20 

CGERU ~ Performs unconjugated rank 1 update 

of a complex general matrix 4-22 

change JCL symbol - JSYMSET 17-32 

change length of block - HPCLMOVE 11-6 

change output value - FSUP 12-33 

change size of heap block - HPNEWLEN 11-9 

Changes a value for a JCL symbol or retrieve 

a JCL symbol - JSYMSET 17-32 

Changes the size of an allocated heap block - 

HPNEWLEN 11-9 

channel programming - DRIVER .17-15 

CHAR - Converts integer to character and vice 

versa. 2-26 

character changes NAMEUST - RNL 12-54 

character conversion - CHAR 2-26 

character conversion - DSASC 8-11 

character move - MVC 10-6 

character read - RE ADC 12-50 

character string length - LEN 2-53 

character translate - TRR1 8-17 

character write - WRITEC 12-81 

CHBM V - Multiplies a complex vector by a 

complex Hermitian band matrix 4-24 

CHCONV - Converts decimal ASCII numerals to 

an integer value 8-10 

check AQIO status - AQSTAT 12-19 

check for multitasking task - TSKTEST 14-29 

check heap - HPCHECK 11-5 

check status of I/O - CHECKMS 12-25 

CHECKDR - Checks status of asynchronous 

random access I/O operation 12-25 

CHECKMS - Checks status of asynchronous 

random access I/O operation 12-25 

Checks status of asynchronous random access 

I/O operation - CHECKMS 12-25 

Checks tape I/O status - CHECKTP 12-26 

Checks the integrity of the heap - HPCHECK. 11-5 

Checks the status of asynchronous queued I/O 

requests - AQSTAT 12-19 

Checks word-addressable file status - WCHECK 12-70 

CHECKTP - Checks tape I/O status 12-26 

CHEMM - Multiplies a complex general matrix 

by a complex Hermitian matrix 4-26 

CHEMV - Multiplies a complex vector by a 

complex Hermitian matrix 4-29 

CHER - Performs Hermitian rank 1 update of a 

complex Hermitian matrix..... 4-31 

CHER2 - Performs Hermitian rank 2 update of a 

complex Hermitian matrix 4-33 

CHER2K - Performs Hermitian rank 2k update of 

a complex Hermitian matrix 4-35 

CHERK - Performs Hermitian rank k update of a 

complex Hermitian matrix 4-38 

Cholesky - LINPACK 4-79 

circular shift - SHIFT 2-70 

clear a multitasking lock - LOCKOFF... 14-22 
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clear floating-point interrupts - CLEARFI 17-11 

clear floating-point interrupts - CLEARFIS 17-12 

clear multitasking - EVCLEAR 14-15 

clear multitasking event - EVCLEAR 14-15 

CLEARBT - Temporarily disables/enables 

bidirectional memory transfers 17-9 

CLEARBTS - Permanently disables/enables 

bidirectional memory transfers 17-10 

CLEARFI - Temporarily prohibits/permits 

floating-point interrupts 17-1 1 

CLEARFIS - Temporarily prohibits/permits 

floating-point interrupts for a job 17-12 

Clears a lock and returns control to the 

calling task - LOCKOFF 14-22 

Clears an event and returns control to the 

calling task - EVCLEAR 14-15 

clock - CLOCK... ..15-3 

CLOCK - Returns the current system-clock time .....15-3 

clock - RTC 15-6 

clock register - RTC 15-6 

CLOG - Computes natural logarithm 2-13 

CLOSDR - Writes master index and closes 

random access dataset 12-28 

close AQIO dataset - AQCLOSE 12-11 

close dataset - WCLOSEU 12-72 

close random access dataset - CLOSMS 12-28 

close random access dataset - WCLOSEU .12-72 

close random access file - WCLOSE 12-71 

close unbuffered dataset - WCLOSEU 12-72 

Closes a word- addressable, random- access 

dataset - WCLOSE 12-7 \ 

Closes a word-addressable, unbuffered 

random-access dataset - WCLOSEU 12-72 

Closes an asynchronous queued I/O dataset or 

file - AQCLOSE 1241 

CLOSEV - Begins user EOV and BOV processing 12-27 

CLOSMS - Writes master index and closes 

random access dataset 12-28 

CLUSEQ - Finds index of clusters within a 

vector. 6-5 

CLUSFGE - Finds real clusters in a vector 6-6 

CLUSFGT - Finds real clusters in a vector 6-6 

CLUSFLE - Finds real clusters in a vector 6-6 

CLUSFLT - Finds real clusters in a vector 6-6 

CLUSIGE - Finds integer clusters in a vector 6-7 

CLUSIGT - Finds integer clusters in a vector 6-7 

CLUSILE - Finds integer clusters in a vector 6-7 

CLUSILT - Finds integer clusters in a vector 6-7 

CLUSNE - Finds index of clusters within a 

vector 6-5 

cluster search - CLUSEQ 6-5 

cluster search - CLUSFLT 6-6 

cluster search - CLUSILT 6-7 

clusters of integer occurrences - CLUSILT 6-7 

clusters of real occurences - CLUSFLT...., 6-6 

CMACH - Returns machine epsilon, small/large 

normalized numbers 17-46 

CMPLX - Converts to type complex ...2-27 

column vector - SMXPY 4-1 15 

common logarithm - ALOG10 2-15 

communications between jobs - IJCOM 17-28 

compare bytes - KOMSTR 10-4 

Compares specified bytes between variables or 

arrays - KOMSTR 10-4 

Compares strings lexically - LGE 2-54 



COMPL - Computes logical complement 2-29 

complement logical - COMPL .2-29 

complex Fast Fourier transform (multiple 

input vectors) - CFFTMLT 5-4 

complex Fast Fourier transform - CFFT2 5-3 

complex general band matrix - CGBMV 4-10 

complex general matrix - CGEMM ..4-13 

complex general matrix - CGERC... 4-20 

complex general matrix - CGERU 4-22 

complex general matrix - CGEMMS 4-15 

complex general matrix - CGEMV 4-18 

complex general matrix - CHEMM .. 4-26 

complex general matrix - CSYMM .,.,4-42 

complex general matrix - CTRMM 4-56 

complex Givens plane rotation matrix - CROTG 4-41 

complex Hermitian band matrix - CHBMV 4-24 

complex Hermitian matrix - CHER 4-3 1 

complex Hermitian matrix - CHER2 4-33 

complex Hermitian matrix - CHER2K 4-35 

complex Hermitian matrix - CHEMM 4-26 

complex Hermitian matrix - CHEM V 4-29 

complex Hermitian matrix - CHERK , 4-38 

complex number computation - AIMAG 2-1 1 

complex plane rotation - CROT 4-40 

complex plane rotation matrix - CROTG 4-41 

complex symmetric matrix - CS YRK 4-48 

complex symmetric matrix - CSYMM 4-42 

complex symmetric matrix - CSYR2K 4-45 

complex triangular band matrix - CTBMV 4-50 

complex triangular banded system of equations 

-CTBSV 4-53 

complex triangular matrix - CTRMM 4-56 

complex triangular matrix - CTRMV 4-58 

complex triangular system of equations - CTRSM 4-60 

complex triangular system of equations - CTRS V 4-62 

complex vector - CGBMV 4-10 

complex vector - CGEMV 4-18 

complex vector - CHBMV 4-24 

complex vector - CHEMV 4-29 

complex vector - CTBMV 4-50 

complex vector - CTRMV 4-58 

complex vector - DOT 4-64 

complex vector - SCAL 4-103 

complex vector - SCOPY .4-105 

complex vector addition - SAXPY .4-102 

complex vector addition - SSUM .....4-133 

complex vector dot product - DOT 4-64 

complex vector exchange - SSWAP 4-134 

complex-to-real Fast Fourier transform 

(multiple input vectors) - RFFTMLT 5-8 

complex-to-real Fast Fourier transform - 

CRFFT2 5-6 

compress data - PACK .9-2 

Compresses stored data - PACK 9-2 

compute arctangent for single argument - ATAN 2-22 

compute arctangent for two arguments - ATAN2 2-24 

compute conjugate - CONJG 2-31 

compute integer ceiling - ICEIL 17-27 

Computes a correlation of two vectors - 

FILTERG 4-69 

Computes a correlation of two vectors - 

FILTERS 4-70 

Computes a dot product (inner product) of two 

real or complex vectors - DOT 4-64 

Computes absolute value - ABS .2-7 
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Computes arccosine -ACOS 2-9 

Computes arcsine - ASIN 2-20 

Computes arctangent for single argument - ATAN 2-22 

Computes arctangent for two arguments - ATAN2 2-24 

Computes bit population parity - POPPAR 2-64 

Computes common logarithm -ALOG10 2-15 

Computes conjugate of a complex number - CONJG ...2-31 

Computes cosine - COS 2-32 

Computes cotangent - COT 2-36 

Computes double-precision product of two real 

numbers - DPROD 2-43 

Computes exponential function - EXP 2-46 

Computes hyperbolic cosine - COSH... 2-34 

Computes hyperbolic sine - SINH 2-79 

Computes hyperbolic tangent - TANH 2-87 

Computes imaginary portion of a complex 

number - AIMAG 2-11 

Computes logical complement - COMPL 2-29 

Computes logical difference - NEQV 2-58 

Computes logical equivalence - EQV 2-44 

Computes logical product - AND 2-17 

Computes logical sum - OR 2-61 

Computes matrix-times-matrix product 

(arbitrary increments) - MXMA 4-88 

Computes matrix- times-matrix product (unit 

increments) - MXM 4-86 

Computes matrix-times-vector product 

(arbitrary increments) - MXVA 4-94 

Computes matrix-times-vector product (unit 

increments) - MXV .4-92 

Computes natural logarithm - ALOG 2-13 

Computes positive difference of two numbers 

- DIM 2-41 

Computes pseudo-random numbers - RAN ...2-66 

Computes real and double-precision truncation 

- AINT 2-12 

Computes remainder of xl/x2 - MOD 2-56 

Computes square root - SQRT 2-82 

Computes tangent -TAN 2-85 

Computes the Euclidean norm of a vector - 

SNRM2 4-116 

Computes the sine - SIN 2-77 

Conditionally transfers control to a 

specified routine - SETRPV 17-45 

CONJG - Computes conjugate of a complex number ...2-31 

conjugate - CONJG 2-31 

conjugate of complex number - CONJG 2-3 1 

conjugated rank 1 update - CGERC .....4-20 

constant coefficient - FOLRC 4-75 

Constructs a Givens plane rotation - CROTG 4-41 

Constructs a Givens plane rotation - SROTG 4-122 

Constructs a modified Givens plane rotation - 

SROTMG 4-126 

continue normal I/O - CONTPIO 12-30 

Continues normal I/O operations - CONTPIO 12-30 

CONTPIO - Continues normal I/O operations 12-30 

control statement - CCS 17-7 

control statement execute - CALLCSP 3-5 

control statement interpreter - CRACK 17-13 

control statement parameters - GETPARAM 17-24 

conversion from IBM - USICTC 8-21 

conversion input type - RNLTYPE 12-57 

conversion subprograms introduction - INTRO 8-1 

convert 24 bit integer - INT24 2-50 

convert 64 bit integer - INT24 2-50 



convert ASCII to integer - CHCONV 8-10 

convert binary to octal - B20CT 8-5 

convert integer - INT24 ....2-50 

convert time - DTTS 15-5 

convert time - TSMT 15-11 

convert time to ASCII - TSDT 15-10 

convert to double precision - DBLE .2-39 

convert to integer - INT .2-49 

convert to real - REAL ...2-68 

Converts 64-bit integer to 24-bit integer and 

vice versa (CFT only) - INT24 2-50 

Converts a Cray 64-bit integer to IBM 

packed-decimal field - USICTP 8-22 

Converts a specified integer to a decimal 

ASCII string representing the integer - 

BICONV 8-6 

Converts a specified number of bytes of an 

IBM packed-decimal field to a 64-bit 

integer field - USPCTC 8-24 

Converts ASCII date and time to time-stamp - 

DTTS 15-5 

Converts CDC 60-bit integers to Cray 64-bit 

integers -INT6064 8-13 

Converts CDC 60-bit single-precision numbers 

to Cray 64-bit single-precision 

numbers and vice versa - FP6064 8-12 

Converts CDC display code character to ASCII 

character and vice versa - DS ASC... 8-11 

Converts Cray 64-bit integers to CDC 60-bit 

integers -INT6460 8-14 

Converts Cray 64-bit integers to either VAX 



INTEGER*2 or INTEGERS numbers - VXICTT 8-32 



Converts Cray 64 -bit single-precision, 

floating-point numbers to IBM 32-bit 

single-precision numbers - USSCTI 8-26 

Converts Cray 64-bit single-precision, 

floating-point numbers to IBM 64-bit double 

precision numbers - USDCTI 8-20 

Converts Cray 64-bit single-precision, 

floating-point numbers to VAX D format 

floating-point numbers - VXDCTI 8-28 

Converts Cray 64-bit single-precision, 

floating-point numbers to VAX G format 

floating-point numbers - VXGCTI 8-30 

Converts Cray 64-bit single-precision, 

floating-point to VAX F format 

single-precision, floating-point - VXSCTI 8-35 

Converts Cray complex numbers to VAX complex 

numbers - VXZCTI .,..8-37 

Converts decimal ASCII numerals to an integer 

value -CHCONV 8-10 

Converts IBM 32-bit floating-point numbers to 

Cray 64-bit single-precision numbers 

-USSCTC 8-25 

Converts IBM 64-bit floating-point numbers to 

Cray 64-bit single-precision numbers 

-USDCTC ....8-19 

Converts IBM EBCDIC data to ASCII data and 

vice versa - USCCTC 8-18 

Converts IBM INTEGER*2 and INTEGER *4 numbers 

to Cray 64-bit integer numbers, and 

vice versa - USICTC 8-21 
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Converts IBM LOGICAL*! and LOGICAL*4 values 



into Cray 64-bit logical values, and 

vice versa - USLCTC 8-23 

converts integer to ASCII string - BICONV 8*6 

Converts integer to character and vice versa 

-CHAR 2-26 

Converts time-stamp to a corresponding 

real-time value, and vice versa - TSMT 15-11 

Converts time-stamps to ASCII date and time - 

TSDT 15-10 

Converts to type complex - CMPLX 2-27 

Converts to type double precision - DBLE 2-39 

Converts to type integer - INT 2-49 

Converts to type real - REAL 2-68 

Converts trailing blanks to nulls and vice 

versa - REN ...8-15 

Converts VAX 32-bit floating-point numbers to 

Cray 64-bit single-precision numbers 

- VXSCTC 8-34 

Converts VAX 64-bit complex numbers to Cray 

complex numbers - VXZCTC 8-36 

Converts VAX 64-bit D format numbers to Cray 

single-precision numbers - VXDCTC ....8-27 

Converts VAX 64-bit G format numbers to Cray 

single-precision numbers - VXGCTC 8-29 

Converts VAX INTEGERS or INTEGER *4 to Cray 

64-bit integers - VXICTC 8-31 

Converts VAX logical values to Cray 64-bit 

logical values VXLCTC S33 

Copies a real or complex vector into another 

vector -SCOPY 4-105 

Copies current register contents to SOUT - 

SNAP 16-13 

Copies either specified sectors or all data 

to EOD - COPYU 13-5 

Copies records, files, or a dataset from one 

dataset to another - COPYR 13*4 

copy block - HPCLMOVE 1 1-6 

Copy register to SOUT - SNAP 16-13 

copy unblocked - COPYU 13-5 

COPYD - Copies records, files, or a dataset 

from one dataset to another 13-4 

COPYF - Copies records, files, or a dataset 

from one dataset to another 13-4 

copying -COPYR 13-4 

copying vectors - SCOPY 4-105 

COPYR - Copies records, files, or a dataset 

from one dataset to another 13-4 

COPYU - Copies either specified sectors or 

all data to EOD 13-5 

correlation - FILTERG 4-69 

correlation - FILTERS 4-70 

correlation of symmetric vectors - FILTERS 4-70 

correlation of two vectors - FILTERS 4-70 

correlation of vectors - FILTERG 4-69 

COS - Computes cosine 2-32 

cos - Computes cosine , . . 2-32 

COS dump -DUMPJOB 16-5 

COS dump -DUMP 16-4 

COS parameters - GETPARAM 17-24 

COS system requests - SYSTEM 17-48 

COSH - Computes hyperbolic cosine 2-34 

cosh - Computes hyperbolic cosine ..2-34 

cosine (hyberbolic) - COSH 2-34 

cosine - COS 2-32 



COT - Computes cotangent , 2-36 

cotangent - COT 2-36 

count 1 bits - POPCNT 2-63 

count arguments - IARGC 17-26 

count leading zero bits - LEADZ .2-52 

count string characters - TRIMLEN 10-7 

Counts number of bits set to 1 - POPCNT 2-63 

Counts number of leading 0 bits - LEADZ 2-52 

CPU time - SECOND 15-7 

CPU time remaining - TREMAIN 15-9 

CPU time return - TSECND 1 4-27 

CPUs available - MAXLCPUS 14-26 

CRACK - Cracks a directive 17-13 

Cracks a control statement - CCS 17-7 

Cracks a directive - CRACK 17-13 

Cracks an expression - CEXPR 17-8 

Cray 64-bit integer conversion - INT6460.,...,,.. 8-14 

Cray 64-bit integer conversion - USICTC 8-21 

Cray 64-bit integer to VAX INTEGER* 2 

conversion - VXICIT 8-32 

Cray 64-bit integer to VAX INTEGER*4 

conversion - VXICIT 8-32 

Cray 64-bit single-precision conversion - 

FP6064 8-12 

Cray 64-bit single-precision floating-point 

conversion - USDCTI 8-20 

Cray 64-bit single-precision floating-point 

conversion - VXGCTI , 8-30 

Cray 64-bit single-precision to 

floating-point conversion - VXDCTL... 8-28 

Cray complex conversion - VXZCTI .8-37 

Cray complex to VAX complex conversion - 

VXZCTI 8-37 

Cray to VAX conversion - VXZCTI 8-37 

CRAYDUMP - Prints a memory dump to a 

specified dataset 16-3 

create subindex - SUNDX 12-63 

Creates an unblocked dataset containing the 

user job area image - DUMPJOB 16-5 

CRFFT2 - Applies a complex-to-real Fast 

Fourier Transform (FFT) 5-6 

CROT - Applies the complex plane rotation 

computed by CROTG 4-40 

CROTG - Constructs a Givens plane rotation 4-41 

CRT screen updating - CURSES .....19-2 

CSCAL - Scales a real or complex vector 4-103 

CSIN - Computes the sine ....2-77 

CSQRT - Computes square root 2-82 

CSSCAL - Scales a real or complex vector ,...,4-103 

CSUM - Sums the elements of a real or complex 

vector .... 4-133 

CSWAP - Swaps two real or complex arrays .....4-134 

CS YMM - Multiplies a complex general matrix 

by a complex symmetric matrix 4-42 

CS YR2K - Performs symmetric rank 2k update of 

a complex symmetric matrix 4-45 

CS YRK - Performs symmetric rank k update of a 

complex symmetric matrix 4-48 

CTBMV - Multiplies a complex vector by a 

complex triangular band matrix 4-50 

CTBSV - Solves a complex triangular banded 

system of equations 4-53 

CTOC - Raises base value to a power .2-65 

CTOI - Raises base value to a power , 2-65 

CTOR - Raises base value to a power ...2-65 
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CTRMM - Multiplies a complex general matrix 

by a complex triangular matrix 4-56 

CTRMV - Multiplies a complex vector by a 

complex triangular matrix .4-58 

CTRSM - Solves a complex triangular system of 

equations with multiple right-hand 

sides 4-60 

CTRSV - Solves a complex triangular system of 

equations 4*62 

current date Julian - DATE 15-4 

current level of calling sequence - TRBKLVL 16-21 

current operating system - UNAME 18-8 

current system time - CLOCK 15-3 

curses - Updates CRT screens 19-2 

custom translation -TRR1 8-17 

cycle time of machine - JCCYCL... 14-20 

cycles -IGETSEC 16-8 

DABS - Computes absolute value 2-7 

DACOS - Computes arccosine 2-9 

DAS IN - Computes arcsine .2-20 

DASS - Performs double-precision arithmetic 2-37 

DASV - Performs double-precision arithmetic ,...2-37 

data accept - ACPTBAD 12-9 

data bad skip - SKIPBAD 12-61 

data buffer a record - FINDMS 12-32 

data compression - PACK 9-2 

data reading - GETWA 12-38 

data reading - GETWAU , 12-40 

data transfer - AQREAD 12-15 

data unpacking - UNPACK 9-5 

data word-addressable - GETWA 12-38 

data word-addressable - GETWAU 12-40 

data writing - WRITE 12-80 

DATAN - Computes arctangent for single 

argument 2-22 

DATAN2 - Computes arctangent for two arguments ....2-24 

dataset access - IFDNT 3-7 

dataset access in system directory - SD ACCESS 3-8 

dataset AQIO close - AQCLOSE 12-1 1 

dataset close - WCLOSEU 12-72 

dataset close random access - CLOSMS 12-28 

dataset creation - IFDNT ....3-7 

dataset edition - NACSED 17-37 

dataset management subprograms introduction - 

INTRO 3-1 

dataset memory reduce - STINDX 12-63 

dataset open - OPENMS 12-42 

dataset open - WOPENU 12-78 

dataset open AQIO - AQOPEN 12-12 

dataset open AQIO -AQOPENDV 12-13 

dataset parameter table (DSP) address - GETDSP 3-6 

dataset position - BACKFILE 13-3 

dataset position - GETPOS 12-34 

dataset size in blocks - NUMBLKS 13-9 

dataset skip - SKIPD 1 3- 10 

dataset tape position - SETTP 12-59 

dataset tape synchronize with program - SYNCH 12-67 

dataset utility routines introduction - INTRO 13-1 

DATE - Returns the current date and the 

current Julian date 15-4 

date conversion - DTTS 15-5 

date returned in Julian format - DATE 15-4 

DAVS - Performs double-precision arithmetic .2-37 

DAW - Performs double-precision arithmetic .2-37 



DBLE - Converts to type double precision .2-39 

DCOS - Computes cosine 2-32 

DCOSH - Computes hyperbolic cosine 2-34 

DCOT - Computes cotangent 2-36 

DDIM - Computes positive difference of two 

numbers 2-41 

DDSS - Performs double-precision arithmetic 2-37 

DDS V - Performs double-precision arithmetic ,..2-37 

DDVS - Performs double-precision arithmetic 2-37 

DDVV - Performs double-precision arithmetic 2-37 

deallocate heap - HPDEALLC ....1 1-7 

DEBUG-Iike snapshot dump - SYMDUMP 16-16 

declare job remnnable - RERUN 17-42 

Declares ajobrerunnable/not rerunnable - 

RERUN 17-42 

decrease heap - HPSHRINK 1 1-10 

decrease heap block - HPNEWLEN 11-9 

DELAY - Do nothing for a fixed period of time 17-14 

delay multitasking event - EVWA1T ....14-19 

delay task - EVWAIT 14-19 

Delays program execution during a queued I/O 

sequence - AQRECALL 12-17 

Delays the calling task until the specified 

event is posted - EVWAIT 14-19 

delete characters for NAMELIST - RNL 12-54 

delimiter NAMELIST change - WNL 12-73 

Determines action if a type mismatch occurs 

across the equal sign on an input 

record - RNLTYPE 12-57 

Determines if a dataset has been accessed or 

created - IFDNT 3-7 

Determines if floating-point interrupts are 

permitted or prohibited - SENSEFI 17-44 

Determines index location of a character 

substring - INDEX 2-48 

Determines the length of a character string - 

LEN .2-53 

Determines whether bidirectional memory 

transfer is enabled or disabled - SENSEBT. 17-43 

DEXP - Computes exponential function .2-46 

DFLOAT - Converts to type double precision .2-39 

difference (logical) - NEQV .2-58 

difference of two numbers (positive) - DIM 2-41 

DIM - Computes positive difference of two 

numbers 2-41 

DINT - Computes real and double-precision 

truncation . .2-12 

directive parameters process - PPL 17-39 

disk dataset positioning - GETPOS 12-34 

disk random access write - WRTTMS 12-83 

divide long integers - LDIV 2-51 

division (double-precision) - DBL_PREC 2-37 

division (triple-precision) - TADD.... 2-84 

division -LDIV 2-51 

DLOG - Computes natural logarithm .2-13 

DLOG10- Computes common logarithm .2-15 

DMAX1 - Returns the largest of all arguments 6-18 

DMIN1 - Returns the smallest of all arguments 6-19 

DMOD - Computes remainder of xl/x2 2-56 

DMSS - Performs double-precision arithmetic 2-37 

DMSV - Performs double-precision arithmetic 2-37 

DMVS - Performs double-precision arithmetic 2-37 

DMV V - Performs double-precision arithmetic 2-37 

DNINT - Finds nearest whole number 2-19 

Do nothing for a fixed period of lime - DELAY 17-14 
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dot product - DOT 4-64 

double precision - DBLE 2-39 

double precision - DBL_PR.EC 2-37 

double precision - DPROD 2-43 

double-precision addition - DBLJPREC 2-37 

double-precision arithmetic - DBLJPREC .....2-37 

double-precision division - DBLJPREC 2-37 

double-precision multiplication - DBL_PREC 2-37 

double-precision product (real numbers) - 

DPROD 2^3 

double-precision subtraction - DBLJPREC... 2-37 

double-precision truncation - AINT 2-12 

DPROD - Computes double-precision product of 

two real numbers 2-43 

DRIVER - Programs a Cray channel on an I/O 

Subsystem (IOS) ..17-15 

DSASC - Converts CDC display code character 

to ASCII character and vice versa ...8-11 

DSIGN - Transfers sign of numbers 2-76 

DSIN - Computes the sine 2-77 

DSINH - Computes hyperbolic sine 2-79 

DSQRT - Computes square root . 2-82 

DSSS - Performs double-precision arithmetic 2-37 

DSS V - Performs double-precision arithmetic 2-37 

DSVS - Performs double-precision arithmetic 2-37 

DSVV - Performs double-precision arithmetic. ..2-37 

DTAN - Computes tangent 2-85 

DTANH - Computes hyperbolic tangent , .2-87 

DTOD - Raises base value to a power .2-65 

DTOI - Raises base value to a power 2-65 

DTOR - Raises base value to a power .2-65 

DTTS - Converts ASCII date and time to 

time-stamp.. , 15-5 

dump - BUFPRINT 14-9 

DUMP - Dumps memory to $OUT 16-4 

dump from regis ters - SNAP 16-13 

dump heap size and address - HPDUMP 11-8 

dump job area - DUMPJOB 16-5 

dump multitasking - BUFDUMP.... 14-8 

dump of memory - DUMP. 16-4 

dump of running program - SYMDUMP 16-16 

dumptoSOUT - DUMP 16-4 

dump to dataset - CRAYDUMP .16-3 

dump to dataset - DUMPJOB 16-5 

dump tuning - BUFTUNE 14-10 

DUMPJOB - Creates an unblocked dataset 

containing the user job area image 16-5 

Dumps memory to $OUT - DUMP 16-4 

Dumps the address and size of each heap block 

-HPDUMP 11-8 

EBCDIC to ASCII conversion - USCCTC 8-18 

EBCDIC translation -TR.... .8-16 

ECHO - Turns on and off the classes of 

messages to the user logfile .....17-16 

echo lines NAMELIST - RNLECHO 12-55 

edition of dataset - NACSED.... 17-37 

Eigenvalue problem - EISPACK 4-65 

EISPACK - Single-precision EISPACK routines 4-65 

EISPACK routines - INTRO 4-1 

elements in a vector - IILZ 6-8 

elements of a complex vector - IS AM AX 6-1 1 

elements of a real vector - ISAMAX 6-1 1 

END - Terminates a job step 17-17 

end Fortran program - EXIT 17-21 
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end job - ABORT 17-5 

end job - END 17-17 

end of file status - EOF 13-7 

end of tape processing - SETSP 12-58 

end-of-dataset status - IOSTAT 13-8 

end-of-file status - IOSTAT . 13-8 

end-of-volume notification - ENDSP 12-31 

end-of-volume processing - STARTSP 12-62 

end-of-volume processing - CLOSE V 12-27 

end-of-volume processing - PROCEOV. 12-45 

ENDRPV - Terminates a job step 17-17 

ENDSP - Requests notification at the end of a 

tape volume . 12-31 

Enters a formatted message in the user and 

system logfiles - REMARKF 17-41 

Enters a message in the user and system log 

files - REMARK 17-40 

environment name - GETENV 18-4 

EOD position - SKIPD 13-10 

EOD status - IOSTAT 13-8 

EOD write -EODW 13-6 

EODW -EODW _I3-6 

EOF - Returns real or integer value EOF status 13-7 

EOF status - IOSTAT 13-8 

EOF write -EODW 13-6 

EOR write - EODW ....13-6 

EOV notification - ENDSP 12-3 1 

EOV processing - CLOSEV 12-27 

EOV processing - PROCEOV 12-45 

EOV processing - SVOLPRC 12-65 

equivalence (logical) - EQV ,2-44 

equivalence - EQV 2-44 

EQV - Computes logical equivalence. .2-44 

ERECALL - Allows a job to suspend itself 

until selected events occur .17-18 

ERREXTT - Requests abort ..17-20 

error unit NAMELIST - RNLECHO .12-55 

Euclidean norm - SNRM2 4-116 

EVASGN - Identifies an integer variable to be 

used as an event ♦ 14-14 

E VCLEAR - Clears an event and returns control 

to the calling task 14-15 

event assign - EVASGN 14-14 

event clear - EVCLEAR 1445 

event post - EVPOST 14-16 

event release - EVREL « 14-17 

event test - EVTEST 14-18 

events -EVCLEAR 14-15 

events - EVPOST 14-16 

EVPOST - Posts an event and returns control 

to the calling task 14-16 

EVREL - Releases the identifier assigned to 

the task 14-17 

EVTEST - Tests an event to determine its 

posted state,.. 14-18 

EVWAIT - Delays the calling task until the 

specified event is posted..,. 14-19 

Exchange Package listing - XPFMT 16-22 

Exchange Package write - FXP 16-6 

execute control statement - CALLCSP.... 3-5 

execute shell command from current process - 

ISHELL 17-30 

Executes a COS control statement - CALLCSP 3-5 

Executes a UNICOS shell command - ISHELL 17-30 

execution time in CPU - SECOND 15-7 
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execution time in CPU - TSECND 14-27 

EXIT - Exits from a Fortran program.... 17-21 

exit from Fortran - EXIT 17-21 

exit job - ERREXIT 17-20 

Exits from a Fortran program - EXIT 17-21 

exp - Computes exponential function 2-46 

EXP - Computes exponential function 2-46 

expand data - UNPACK 9-5 

Expands stored data - UNPACK 9-5 

exponential function - EXP 2*46 

expression - CEXPR 17-8 

extend block - HPCLMOVE 11-6 

Extends a block or copies block contents into 

a larger block - HPCLMOVE 11-6 

Fast Fourier transform (complex with multiple 

input vectors) - CFFTMLT .5-4 

Fast Fourier transform - CFFT2 5-3 

Fast Fourier transform - CRFFT2 5-6 

Fast Fourier transform - INTRO „ , 5-1 

Fast Fourier transform - RCFFT2 .5-7 

Fast Fourier transform - RFFTMLT 5-8 

Fast Fourier transform for multiple input 

vectors - RFFTMLT 5-8 

Fast Fourier transform routines introduction 

-INTRO 5-1 

Fast Fourier transforms - CFFTMLT 5-4 

FFT -RCFFT2 5-7 

FFT-CFFT2 5-3 

FFT - CFFTMLT 5-4 

FFT - CRFFT2 ....5-6 

FFT -INTRO 5-1 

FFT -RFFTMLT . 5-8 

field finder - TMMSC 11-17 

field length reduction - MEMORY 17-35 

file check - WCHECK 12-70 

file close -WCLOSE 12-71 

file skip -SKIPR 13-11 

file tape position - SETTP.... 12-59 

filter -FILTERG 4-69 

filter -OPFILT 4-98 

filter routines - INTRO 4-1 

FILTERG - Computes a correlation of two 

vectors 4-69 

FILTERS - Computes a correlation of two 

vectors ♦ .4-70 

find field - TMMSC 11-17 

find table field - TMSRC 11-20 

FINDCH - Searches a variable or an array for 

an occurrence of a character string .10-3 

FINDMS - Reads record into data buffers 12-32 

Finds all array elements equal to or not 

equal to the target - WHENEQ 6-22 

Finds all integer array elements in relation 

to the integer target - WHENILT ....6-24 

Finds all real array elements in relation to 

the real target - WHENFLT 6-23 

Finds array element equal or not equal to 

target - ISRCHEQ 6-13 

Finds first index of largest absolute value 

in vectors - ISAMAX 6-1 1 

Finds first integer array element in relation 

to an integer target - ISRCHILT 6-15 



Finds first real array element in relation to 

area! target - ISRCHFLT 6-14 

Finds index of clusters within a vector - 

CLUSEQ .6-5 

Finds integer clusters in a vector - CLUSILT 6-7 

Finds maximum, minimum, or minimum absolute 

value -ISMAX 6-12 

Finds nearest integer -N1NT 2-60 

Finds nearest whole number - ANINT 2-19 

Finds real clusters in a vector - CLUSFLT 6-6 

Finds the index of occurrences equal or not 

equal to a scalar within a field in a 

vector - WHENMEQ 6-25 

Finds the index of occurrences in relation to 

a scalar within a field in a vector 

-WHENMLT 6-26 

Finds the index of the first occurrence equal 

or not equal to a scalar within a 

field of a vector - ISRCHMEQ 6-16 

first-order linear recurrence - FOLRC 4-75 

first-order linear recurrence - FOLRN 4-76 

first-order linear recurrence - FOLRNP 4-77 

first-order linear recurrences - FOLR 4-71 

first-order linear recurrences - FOLR2 4-73 

fixed length record sort - ORDERS ...7-2 

FLOAT - Converts to type real 2-68 

floating point conversion - USDCTI 8-20 

floating point to 32-bit single-precision - 

USSCTI 8-26 

floating point to single-precision conversion 

- VXDCTI 8-28 

floating-point conversion - USSCTC 8-25 

floating-point interrupts - CLEARFI 17-1 1 

floating-point interrupts - CLEARFIS 17-12 

floating-point interrupts - SENSEFI 17-44 

floating-point to double-precision - USDCTI 8-20 

floating-point to single-precision conversion 

- USSCTC 8-25 

floating-point to single-precision number 

conversion - USDCTC , 8-19 

floating-point to VAX F format single 

precision - VXSCTI 8-35 

floating -poiont to VAX G format single 

precision - VXGCTI 8-30 

FOLR - Solves first-order linear recurrences 4-71 

FOLR2 - Solves first-order linear recurrences 

without overwriting operand vector .4-73 

FOLR2P - Solves first-order linear 

recurrences without overwriting operand vector ...4-73 
FOLRC - Solves first-order linear recurrence 

with constant coefficient .4-75 

FOLRN - Solves for the last term of 

first-order linear recurrence 4-76 

FOLRNP - Solves for last term of a 

first-order linear recurrence 4-77 

FOLRP - Solves first-order linear recurrences 4-71 

format Exchange Package - FXP 16-6 

format output control - WNL 12-73 

Formats and writes the contents of the 

Exchange Package - FXP 16-6 

Formatted dump of multitasking history trace 

buffer - BUFPRINT 14-9 

Fortran argument - GETARG 17-22 

Fortran character string length - LEN 2-53 

Fortran exit - EXIT 17-21 
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Fortran interface to getenv - GETENV 18-4 

Fortran intrinsic - ABS 2-7 

Fortran intrinsic - ACOS 2-9 

Fortran intrinsic - AIMAG 2-1 1 

Fortran intrinsic - AINT 2-12 

Fortran intrinsic - ALOG . 2-13 

Fortran intrinsic - ALOG10 „. 2-15 

Fortran intrinsic - AND 2-17 

Fortran intrinsic - ANINT 2-19 

Fortran intrinsic - ASIN 2-20 

Fortran intrinsic - ATAN 2-22 

Fortran intrinsic - ATAN2 2-24 

Fortran intrinsic - CMPLX 2-27 

Fortran intrinsic - COMPL 2-29 

Fortran intrinsic - CONJG 2-31 

Fortran intrinsic - COS.., 2-32 

Fortran intrinsic - COSH 2-34 

Fortran intrinsic - COT 2-36 

Fortran intrinsic - DIM 2-41 

Fortran intrinsic - DPROD 2-43 

Fortran intrinsic - EQV 2-44 

Fortran intrinsic - EXP ...2-46 

Fortran intrinsic - INT 2-49 

Fortran intrinsic - LEADZ 2-52 

Fortran intrinsic - MASK 2-55 

Fortran intrinsic - MOD .2-56 

Fortran intrinsic - NEQV 2-58 

Fortran intrinsic - NINT 2-60 

Fortran intrinsic - OR 2-61 

Fortran intrinsic - POPCNT 2-63 

Fortran intrinsic - POPPAR 2-64 

Fortran intrinsic - RAN 2-66 

Fortran intrinsic - REAL.. .2-68 

Fortran intrinsic - SHIFT 2-70 

Fortran intrinsic - SHIFTL.... . 2-72 

Fortran intrinsic - SHIFTR 2-74 

Fortran intrinsic - SIGN... 2-76 

Fortran intrinsic - SIN 2-77 

Fortran intrinsic - SINH 2-79 

Fortran intrinsic - SQRT 2-82 

Fortran intrinsic - TAN 2-85 

Fortran intrinsic - TANH .2-87 

Fortran output change - FSUP ..12-33 

Fortran snapshot dump - SYMDUMP .16-16 

Fourier transform - INTRO 5-1 

Fourier transform - RCFFT2 5-7 

FP6064 - Converts CDC 60-bit single-precision 
numbers to Cray 64 -bit 

single-precision numbers and vice versa 8-12 

FP6460 - Converts CDC 60-bit single-precision 
numbers to Cray 64-bit 

single-precision numbers and vice versa 8-12 

free block links for heap - HPDUMP 1 1-8 

FSUP - Output a value in an argument as blank 12-33 

full record read - READC 12-50 

full-record mode - WRITE 12-80 

full-record mode - WRITEC 12-81 

full-record read - READ 12-49 

function key definitions - CURSES 19-2 

FXP - Formats and writes the contents of the 

Exchange Package 16-6 

GATHER - Gathers a vector from a source vector 4-78 

gather-scatter routines - INTRO 4-1 

gathering vector - GATHER 4-78 



Gathers a vector from a source vector - GATHER 4-78 

generates integer index - INDEX 2-48 

get option letter - GETOPT 18-5 

GETARG - Return Fortran command-line argument. ...17-22 
GETARG - Returns number of command-line 

arguments 17-26 

GETDSP - Searches for a Dataset Parameter 

Table (DSP) 3-6 

getenv - Returns value for environment name 18-4 

GETLPP - Returns lines per page 17-23 

GETNAMEQ - Returns name of the caller 16-7 

getopt - Gets option letter from argument 

vector 18-5 

GETPARAM - Gets parameters 17-24 

GETPOS - GETPOS, SETPOS - Returns the current 

position of interchange tape 12-34 

GETPOS, SETPOS - Returns the current position 

of interchange tape - GETPOS 12-34 

Gets name of current operating system - UNAME........18-8 

Gets option letter from argument vector - 

GETOPT.. 18-5 

Gets parameters - GETPARAM 17-24 

GETTP - Receives position information about 

an opened tape dataset or file - GETTP 12-36 

GET WA - Synchronously and asynchronously 

reads data 12-38 

GETWAU - Asynchronously reads a number of 

words from the disk, directly to user 12-40 

Givcns - CROTG 4-41 

Givens - SROTG 4-122 

Givens - SROTM 4-124 

Givens - SROTMG 4-126 

Givens plane rotation application - SROTM .4-124 

Givens plane rotation construction - SROTG 4-122 

Givens plane rotation construction - SROTMG 4-126 

hardware standard name - UNAME 18-8 

heap address - HPDUMP 1 1,8 

heap allocation - HPALLOC 11-4 

heap block adjust - HPNEWLEN 1 1-9 

heap block length - IHPLEN 11-1 1 

heap blocks dump - HPDUMP 11-8 

heap deallocation - HPDEALLC 11-7 

heap decrease - HPSHRINK 11-10 

heap information - HPDUMP 11-8 

heap integrity check - HPCHECK 11-5 

heap management and table management 

introduction - INTRO 11-1 

heap size - HPDUMP 11-8 

heap statistics - IHPSTAT 11-12 

Hermitian - CHBMV 4-24 

Hermitian - CHEMM 4-26 

Hermitian - CHEMV .4-29 

Hermitian - CHER 4-31 

Hermitian - CHER2 4-33 

Hermitian - CHER2K 4-35 

Hermitian - CHERK 4-38 

Hermitian rank 1 update - CHER 4-31 

Hermitian rank 2 update - CHER2 4-33 

Hermitian rank 2k update - CHER2K 4-35 

Hermitian rank k update - CHERK 4-38 

history trace buffer dump - BUFDUMP 14-8 

history trace buffer dump - BUFPRINT 14-9 
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history trace buffer dump add entries - 

BUFUSER 14-13 

history trace buffer tuning parameters - 

BUFTUNE ....14-10 

hold for some time period - DELAY 17-14 

Horner's method - FOLRN 4-76 

HP ALLOC - Allocates a block of memory from 

the heap 11-4 

HPCHECK - Checks the integrity of the heap 1 1-5 

HPCLMOVE - Extends a block or copies block 

contents into a larger block 1 1-6 

HPDEALLC - Returns a block of memory to the 

list of available space 11-7 

HPDUMP - Dumps the address and size of each 

heap block 11-8 

HPNEWLEN - Changes the size of an allocated 

heap block 11-9 

HPSHRINK - Returns an unused portion of heap 

to the operating system..... 11-10 

hyberbolic cosine - COSH ..... 2-34 

hyperbolic sine - SINH 2-79 

hyperbolic tangent - TANH 2-87 

I/O asynchronous - AQOPEN .12-12 

I/O asynchronous - AQOPENDV 12-13 

I/O check of status - CHECKMS 12-25 

I/O mode asynchronous - ASYNCMS 12-24 

I/O mode to synchronous - SYNCMS 12-68 

I/O normal - CONTPIO 12-30 

I/O open - OPENMS 12-42 

I/O read asynchronous - AQREAD 12-15 

I/O routines introduction - INTRO 12-1 

I/O stop (AQIO) - AQSTOP 12-20 

VO wait (AQIO) - AQWATT 12-21 

I/O wait - WA1TMS 12-69 

VO write (AQIO) - AQWRTTE 12-22 

LABS - Computes absolute value . 2-7 

IARGC - Returns number of command-line 

arguments 17-26 

IBM 32-bit floating-point conversion - USSCTC 8-25 

IBM 64-bit floating-point conversion - USDCTC 8-19 

ibm floating-point - READIBM. 12-51 

IBM packed-decimal conversion - USPCTC 8-24 

ibm words read - READIBM ....12-51 

IBM words write - WRITIBM 12-82 

ibm-from-Cray read - READIBM 12-51 

ICAMAX - Finds first index of largest 

absolute value in vectors 6-1 1 

ICEIL - Returns integer ceiling of a rational 

number 17-27 

ICHAR - Converts integer to character and 

vice versa 2-26 

Identifies an integer variable intended for 

use as a lock - LOCKASGN.. 14-21 

Identifies an integer variable to be used as 

an event - EVASGN 14-14 

Identifies an integer variable to use as a 

barrier -BARASGN 14-5 

IDIM - Computes positive difference of two 

numbers 2-41 

IDINT - Converts to type integer 2-49 

IDNINT - Finds nearest integer 2-60 

IEOF - Returns real or integer value EOF 

status 13-7 



IFDNT - Determines if a dataset has been 

accessed or created 3-7 

IFDC - Converts to type integer 2-49 

IGETSEC - Returns the cycles charged to a job 16-8 

IGTBYT - Replaces a byte in a variable or an 

array 10-2 

IHPLEN - Returns the length of a heap block 11-1 1 

IHPSTAT - Returns statistics about the heap 11-12 

TTLZ - Returns number of occurrences of 

object in a vector 6-8 

IJCOM - Allows a job to communicate with 

another job .17-28 

ILLZ - Returns number of occurrences of 

object in a vector ...6-8 

ILSUM - Returns number of occurrences of 

object in a vector 6-8 

imaginary portion of complex number - AIMAG ,2-11 

increase heap block - HPNEWLEN.. 11-9 

increasing vectorization - EISPACK 4-65 

INDEX - Determines index location of a 

character substring 2-48 

index location - INDEX .2-48 

index of clusters within a vector - CLUSEQ 6-5 

index of elements of a vector - ISAMAX 6-1 1 

index write master - CLOSMS 12-28 

Indicates output line length - WNLLONG 12-75 

INFLMAX - Searches for the maximum or minimum 

value in a table 6-9 

INFLMIN - Searches for the maximum or minimum 

value in a table 6-9 

Mtializes/terminates special BOV/EOV 

processing (obsolete) - S VOLPRC 12*65 

Initiates a task - TSKSTART 14-28 

Initiates detailed tracing of every call and 

return - SETPLIMQ 16-12 

inner product - DOT. .4-64 

input - READ 12-49 

input type mismaich - RNLTYPE 12-57 

input wait for end - WATTMS 12-69 

INT - Converts to type integer 2-49 

INT24 - Converts 64-bit integer to 24-bit 

integer and vice versa (CFT only) 2-50 

INT6064 - Converts CDC 60-bit integers to 

Cray 64-bit integers .8-13 

INT6460 - Converts Cray 64-bit integers to 

CDC 60-bit integers 8-14 

integer - INT .2-49 

integer array element - ISRCHEQ 6-13 

integer array element - ISRCHILT .6-15 

integer array element - ISRCHMLT 6-17 

integer array element - OSRCHI 6-20 

integer array element - OSRCHM 6-21 

integer array elements - WHENEQ 6-22 

integer array elements - WHENILT 6-24 

integer array search - OSRCHM 6-21 

integer array search - WHENILT 6-24 

integer ceiling value - ICEIL 17-27 

integer cluster - CLUSILT 6-7 

integer conversion - CHAR 2-26 

integer converter - INT24 2-50 

integer divide - LDIV 2-51 

integer division - LDIV 2-51 

integer from ASCII conversion - CHCONV 8-10 

integer to ASCII conversion - BICONV ...8-6 

integer to packed-decimal conversion - USICTP 8-22 
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INTEGERS to integer conversion - USICTC 8-21 

INTEGERM to integer conversion - USICTC 8-21 

integrity of heap check - HPCHECK 11-5 

inter-job communication - IJCOM. 17-28 

interface to C library routines introduction 

-INTRO 18-1 

interrupts floating-point - SENSEFI ....17-44 

interrupts floating-point - CLEARH 17-11 

interrupts floating-point - CLEARFIS 17-12 

INTMAX - Searches for the maximum or minimum 

value in an integer vector 6-10 

INTMIN - Searches for the maximum or minimum 

value in an integer vector 6-10 

intrinsic - ABS .2-7 

intrinsic - ACOS 2-9 

intrinsic - ALOG 2-13 

intrinsic -ALOG10 2-15 

intrinsic - AIMAG 2-1 1 

intrinsic - AINT 2-12 

intrinsic - AND 2-17 

intrinsic - ANINT 2-19 

intrinsic - ASIN 2-20 

intrinsic - ATAN 2-22 

intrinsic - ATAN2 .2-24 

intrinsic - CMPLX 2-27 

intrinsic - COMPL 2-29 

intrinsic - CONJG 2-31 

intrinsic - COS 2-32 

intrinsic - COSH 2-34 

intrinsic - COT 2-36 

intrinsic - DIM 2-41 

intrinsic - DPROD 2-43 

intrinsic - EQV 2^4 

intrinsic - EXP 2-46 

intrinsic - INT 2^9 

intrinsic - LEADZ 2-52 

intrinsic - MASK .......2-55 

intrinsic - MOD 2-56 

intrinsic - NEQV 2-58 

intrinsic - NINT ....2-60 

intrinsic -OR .2-61 

intrinsic - POPCNT . 2-63 

intrinsic - POPPAR 2-64 

intrinsic ■ RAN 2-66 

intrinsic - REAL 2-68 

intrinsic - SHIFT .2-70 

intrinsic - SHIFTL .2-72 

intrinsic - SHIFTR 2-74 

intrinsic - SIGN 2-76 

intrinsic - SIN 2-77 

intrinsic - SINH 2-79 

intrinsic - SQRT 2-82 

intrinsic - TAN 2-85 

intrinsic - TANH 2-87 

introduction to byte and bit manipulation 

routines - INTRO 10-1 

introduction to conversion subprograms - INTRO 8-1 

introduction to dataset management 

subprograms - INTRO 3-1 

introduction to dataset utility routines - 

INTRO 13-1 

introduction to Fast Fourier Transform 

routines - INTRO 5-1 



introduction to heap management and table 

management - INTRO 1 1-1 

introduction to I/O routines - INTRO .12-1 

introduction to library subprograms - INTRO 1-1 

introduction to linear algebra subprograms - 

INTRO. 4-1 

introduction to multitasking routines - INTRO 14-1 

introduction to packing routines - INTRO ....9-1 

introduction to programming aid routines - 

INTRO 16-1 

introduction to search routines - INTRO 6-1 

introduction to sorting routines - INTRO 7-1 

introduction to system interface routines - 

INTRO 17-1 

introduction to the common math subprograms - 

INTRO .2-1 

introduction to the interface to C library 

routines - INTRO 18-1 

introduction to the miscellaneous UN1COS 

routines - INTRO 19-1 

introduction to timing routines - INTRO .15-1 

inverse of square matrix - MINV 4-82 

IOS channel program - DRIVER 17-15 

IOSTAT - Returns EOF and EOD status 13-8 

IRTC - Return real-time clock values 15-6 

ISAMAX - Finds first index of largest 

absolute value in vectors... 6-1 1 

ISAM IN - Finds maximum, minimum, or minimum 

absolute value , 6-12 

ISHELL - Executes a UNICOS shell command 17-30 

ISIGN - Transfers sign of numbers .2-76 

ISMAX - Finds maximum, minimum, or minimum 

absolute value 6-12 

ISMIN - Finds maximum* minimum, or minimum 

absolute value 6-12 

ISRCHEQ - Finds array element equal or not 

equal to target..... 6-13 

ISRCHFGE - Finds first real array element in 

relation to a real target ...6-14 

ISRCHFGT - Finds first real array element in 

relation to a real target 6-14 

ISRCHFLE - Finds first real array element in 

relation to a real target 6-14 

ISRCHFLT - Finds first real array element in 

relation to a real target 6-14 

ISRCHIGE - Finds first integer array element 

in relation to an integer target 6-15 

ISRCHIGT - Finds first integer array element 

in relation to an integer target 6-15 

ISRCHILE - Finds first integer array element 

in relation to an integer target 6-15 

ISRCHILT - Finds first integer array element 

in relation to an integer target 6-15 

ISRCHMEQ - Finds the index of the first 

occurrence equal or not equal to a scalar 

within a field of a vector 6-16 

ISRCHMGE - Searches vector for logical match 6-17 

ISRCHMGT - Searches vector for logical match 6-17 

ISRCHMLE - Searches vector for logical match 6-17 

ISRCHMLT - Searches vector for logical match 6-17 

ISRCHMNE - Finds the index of the first 

occurrence equal or not equal to a scalar 

within a field of a vector 6-16 
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ISRCHNE - Finds array element equal or not 

equal to target 6-13 

IS UP - Output a value in an argument as blank 12-33 

ITOI - Raises base value to a power 2-65 

J AT - ACTTABLE 17-6 

JCCYCL - Returns machine cycle time 14-20 

JCL symbol change - JSYMSET 17-32 

JD ATE - Returns the current date and the 

current Julian date , 15-4 

JNAME - Returns the job name 17-31 

Job Accounting Table - ACTTABLE 17-6 

job area dump - DUMPJOB 16-5 

job communication - DCOM , 17-28 

job cycles - IGETSEC 16-8 

job memory changes - MEMORY 17-35 

job name - JNAME 17-31 

job suspend - ERECALL 17-18 

job time in CPU - TSECND 14-27 

job time left - TREMAIN 15-9 

JSYMGET - Changes a value for a JCL symbol or 

retrieve a JCL symbol 17-32 

JSYMSET * Changes a value for a JCL symbol or 

retrieve a JCL symbol 17-32 

Julian date list - DATE 15-4 

key words process - PPL 17-39 

KOMSTR - Compares specified bytes between 

variables or arrays 10-4 

large radix sorting - ORDERS 7-2 

largest absolute value - ISAMAX... 6-1 1 

largest argument - MAX 6-18 

largest normalized number - SMACH 17-46 

LDSS - Performs 64-bit integer divide 2-51 

LDSV - Performs 64-bit integer divide 2-51 

LDVS - Performs 64-bit integer divide 2-51 

LDVV - Performs 64-bit integer divide 2-51 

leading zero bit count - LEADZ 2-52 

LEADZ - Counts number of leading 0 bits 2-52 

left circular shift - SHIFT 2-70 

left shift - SHIFTL 2-72 

LEN - Determines the length of a character 

string 2-53 

length of block change - HPCLMOVE 11-6 

length of heap block - IHPLEN 11-1 1 

length of output line - WNLLONG 12-75 

Level 1 BLAS - CROT 4-40 

Level 1 BLAS - CROTG 4-41 

Level 1 BLAS - DOT 4-64 

Level 1 BLAS - INTRO 4-1 

Level 1 BLAS - SASUM 4-101 

Level 1 BLAS - SAXPY 4-102 

Level 1 BLAS - SCAL.. 4-103 

Level 1 BLAS - SCOPY 4-105 

Level 1 BLAS - SMXPY 4415 

Level 1 BLAS - SNRM2 4-116 

Level 1 BLAS - SPDOT 4-120 

Level 1 BLAS - SROT 4-121 

Level 1 BLAS - SROTG 4-122 

Level 1 BLAS - SROTM 4-124 

Level 1 BLAS - SROTMG 4426 

Level 1 BLAS - SSUM 4433 

Level 1 BLAS - SS WAP 4-134 

Level 1 BLAS - SXMPY 4-156 
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Level 2 BLAS - CGBMV 4-10 

Level 2 BLAS - CGEMV 4-18 

Level 2 BLAS - CGERC 4-20 

Level 2 BLAS - CGERU 4-22 

Level 2 BLAS - CHBMV 4-24 

Level 2 BLAS - CHEMV 4-29 

Level 2 BLAS - CHER 4-31 

Level 2 BLAS - CHER2 4*33 

Level 2 BLAS - CTBMV ..4-50 

Level 2 BLAS - CTBS V 4-53 

Level 2 BLAS - CTRMV 4-58 

Level 2 BLAS - CTRS V 4-62 

Level 2 BLAS - INTRO 4-1 

Level 2 BLAS - SGBMV 4-106 

Level 2 BLAS - SGEMV 4-1 13 

Level 2 BLAS - SGER .4414 

Level 2 BLAS - SSBMV .... .....4431 

Level 2 BLAS - SS YMV .4-138 

Level 2 BLAS - SS YR 4439 

Level 2 BLAS - SSYR2 4-140 

Level 2 BLAS - STBMV 4-146 

Level 2 BLAS - STBSV 4448 

Level 2 BLAS - STRMV 4-152 

Level 2 BLAS - STRSV 4155 

Level 3 BLAS (CRI extension) - CGEMMS 4-15 

Level 3 BLAS (CRI extension) - SGEMMS 4-1 10 

Level 3 BLAS - CGEMM 4-13 

Level 3 BLAS - CHEMM 4-26 

Level 3 BLAS - CHER2K 4-35 

Level 3 BLAS - CHERK 4-38 

Level 3 BLAS - CSYMM ....4-42 

Level 3 BLAS - CSYR2K 4^5 

Level 3 BLAS - CSYRK. 4-48 

Level 3 BLAS - CTRMM 4-56 

Level 3 BLAS - CTRSM ...4-60 

Level 3 BLAS - INTRO 4-1 

Level 3 BLAS - SGEMM 4408 

Level 3 BLAS - SSYMM .4435 

Level 3 BLAS - SSYR2K 4-141 

Level 3 BLAS - SSYRK 4-144 

Level 3 BLAS - STRMM 4-150 

Level 3 BLAS - STRSM 4-153 

lexical comparison - LGE 2-54 

LGE - Compares strings lexically 2-54 

LGO - Loads an absolute program from a 

dataset containing a binary image as the 

first record 17-33 

LGT - Compares strings lexically 2-54 

library scheduler tuning - TSKTUNE ..14-30 

library subprogram introduction - INTRO 14 

line length on output - WNLLONG 12-75 

linear algebra subprograms introduction - 

INTRO..... .4-1 

linear equations - LINPACK 4-79 

linear equations - MINV 4-82 

linear equations - OPFILT 4-98 

linear equations - STBSV 4-148 

linear equations - STRSV 4-155 

linear recurrence - FOLR 4-71 

linear recurrence - FOLR2 4-73 

linear recurrence - FOLRC 4-75 

linear recurrence - FOLRN ,....4-76 

linear recurrence - FOLRNP 4-77 

linear recurrence - RECPP .4-99 

linear recurrence - RECPS .4-100 
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linear recurrence - SOLR 4-1 17 

linear recurrence routines - INTRO . 4*1 

lines per page - GETLPP 17-23 

UNPACK - Single-precision real and complex 

UNPACK routines 4-79 

UNPACK routines - INTRO 44 

UNT - Converts 64-bit integer to 24-bit 

integer and vice versa (CFT only) 2-50 

list calling sequence - TRBK .16-20 

list Exchange Package - XPFMT .16-22 

list subroutines - TRBK 16-20 

Lists all subroutines active in the current 

calling sequence - TRBK 16-20 

LLE - Compares strings lexically 2-54 

LLT - Compares strings lexically 2-54 

load absolute program - LGO 17-33 

load overlay - OVERLAY 17-38 

load program from dataset - LGO 17-33 

Loads an absolute program from a dataset 

containing a binary image as the first 

record - LGO 17-33 

Loads an overlay and transfers control to the 

overlay entry point - OVERLAY 17-38 

LOC - Returns memory address of variable ot 

array 17-34 

locate memory address - LOC 17-34 

locate table field - TMSRC 1 1-20 

LOCKASGN - Identifies an integer variable 

intended for use as a lock. 14-21 

LOCKOFF - Clears a lock and returns control 

to the calling task 14-22 

LOCKON - Sets a lock and returns control to 

the calling task 14-23 

LOCKREL - Releases the identifier assigned to 

a lock 14-24 

LOCKTEST - Tests a lock to determine its 

state (locked or unlocked) 14-25 

log - Computes natural logarithm 243 

log 10 - Computes common logarithm 245 

logfile messages - ECHO 17-16 

logical complement - COMPL 2-29 

logical CPUs available - MAXLCPUS 14-26 

logical difference - NEQV 2-58 

logical equivalence - EQV 2-44 

logical file table - ADDLFT. 3-4 

logical product - AND 2-17 

logical sum - OR 2-61 

logical to LOGICAL*l conversion - USLCTC. 8-23 

logical to LOGICAL*4 conversion - USLCTC 8-23 

LOGICAL*! to logical conversion - USLCTC 8-23 

LOGICALM to logical conversion - USLCTC 8-23 

lowercase letters - TR 8-16 

machine epsilon - SMACH 17-46 

Makes bad data available - ACPTBAD 12-9 

Makes requests of the operating system - 

SYSTEM 17-48 

manipulate memory - MEMORY .« 17-35 

Manipulates a job's memory allocation and/or 

its mode of field length reduction - 

MEMORY.. 17-35 

MASK - Returns a bit mask 2-55 

master index write - CLOSMS 12-28 

math library introduction - INTRO 2-1 



matrix inverse and multiplication routines - 

INTRO.... ..4-1 

matrix times matrix multiplication - MXMA 4-88 

matrix times matrix multiplication - CGEMM 4-13 

matrix times matrix multiplication - CGEMMS 4-15 

matrix times matrix multiplication - CHEMM 4-26 

matrix times matrix multiplication - CS YMM 4-42 

matrix times matrix multiplication - CTRMM 4-56 

matrix times matrix multiplication - MXM 4-86 

matrix times matrix multiplication - SGEMM .4-108 

matrix times matrix multiplication - SGEMMS .4-1 10 

matrix times matrix multiplication - SS YMM . 4-135 

matrix times matrix multiplication - STRMM 4-150 

matrix times vector multiplication - CGBMV 4-10 

matrix times vector multiplication - CGEMV 4-18 

matrix times vector multiplication - CHBMV..... .4-24 

matrix times vector multiplication - CHEM V 4-29 

matrix times vector multiplication - CTBMV 4-50 

matrix times vector multiplication - CTRMV ....4-58 

matrix times vector multiplication - MXV 4-92 

matrix times vector multiplication - MXVA 4-94 

matrix times vector multiplication - SGBMV 4-106 

matrix times vector multiplication - SGEMV 4-1 13 

matrix times vector multiplication - SMXPY ....4-1 15 

matrix times vector multiplication - SSBMV 4-131 

matrix times vector multiplication - SSYMV 4-138 

matrix times vector multiplication - STBMV 4-146 

matrix times vector multiplication - STRMV 4-152 

matrix times vector multiplication - SXMPY. .4-156 

MAX0 - Returns the largest of all arguments 6-18 

MAX1 - Returns the largest of all arguments 6-18 

maximum - INTRO 6-1 

maximum - IS MAX ..... 6-12 

maximum CPUs available - MAXLCPUS 14-26 

maximum value in a vector - INFLMAX ,. 6-9 

maximum value in a vector - INTMAX .6-10 

maximum vector element value - ISMAX 6-12 

MAXLCPUS - Returns the maximum number of 

logical CPUs available 14-26 

MEMORY - Manipulates a job's memory 
allocation and/or its mode of field length 

reduction 17-35 

memory address - LOC 17-34 

memory allocation flieap) - HPALLOC 11-4 

memory bidirectional transfer - SENSEBT 17-43 

memory dump - CRAYDUMP 16-3 

memory less for dataset - STTNDX 12-63 

memory manipulation - MEMORY..... 17-35 

memory move - TMM VE 1 1-18 

memory request - TMMEM.... 11-16 

memory table allocate - TMATS 11-15 

memory to heap return - HPDEALLC 11-7 

message classes controlling - ECHO 17-16 

message control COS - ECHO 17-16 

MIN0 - Returns the smallest of all arguments 6-19 

MINI - Returns the smallest of all arguments 6-19 

minimum - INTRO 6-1 

minimum - ISMAX.... . 6-12 

minimum absolute value of vector element - 

ISMAX... 6-12 

minimum value in a vector - INFLMAX ....6-9 

minimum value in a vector - INTMAX 6-10 

minimum vector element value - ISMAX 6-12 
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MINV - Solves systems of linear equations by 

inverting a square matrix 4-82 

miscellaneous UNICOS routines introduction - 

INTRO 19-1 

MOD - Computes remainder of xl/x2 2-56 

mode asynchronous - AS YNCMS 12-24 

mode to synchronous - SYNCMS 12-68 

modified Givens plane rotation - SROTM .....4-124 

modified Givens plane rotation - SROTMG 4-126 

Modifies tuning parameters within the library 

scheduler - TSKTUNE 14-30 

modify heap block - HPNEWLEN .11-9 

modify output value - FSUP 12-33 

modify tuning parameters library scheduler - 

TSKTUNE.,. .....14-30 

modify tuning parameters multitasking - 

TSKTUNE 14-30 

monitor performance - PERF 16-9 

MOVBIT - Moves bytes or bits from one 

variable or array to another .....10-5 

move block - HPCLMOVE 11-6 

move bytes or bits - MOV 10-5 

move characters - MVC .....10-6 

move memory words - TMM VE 11-18 

Moves bytes or bits from one variable or 

array to another - MOV.. 10-5 

Moves characters from one memory area to 

another -MVC , 10-6 

Moves memory (words) - TMMVE..... 1 1-18 

MTTS - Converts time-stamp to a corresponding 

real-time value, and vice versa.... 15-11 

multipass sorting - ORDERS 7-2 

multiple right-hand sides - CTRSM ....4-60 

multiple right-hand sides - STRSM 4-153 

multiple-input vector complex Fast Fourier 

transform - CFFTMLT 5-4 

multiplication (double-precision) - DBL_PREC 2-37 

multiplication (triple-precision) - TADD 2-84 

Multiplies a column vector by a matrix and 

adds the result to another column vector 

-SMXPY 4-115 

Multiplies a complex general matrix by a 

complex general matrix - CGEMM 4-13 

Multiplies a complex general matrix by a 

complex general matrix using Strassen*s 

algorithm - CGEMMS 4-15 

Multiplies a complex general matrix by a 

complex Hermitian matrix - CHEMM 4-26 

Multiplies a complex general matrix by a 

complex symmetric matrix - CS YMM 4-42 

Multiplies a complex general matrix by a 

complex triangular matrix - CTRMM 4-56 

Multiplies a complex vector by a complex 

general band matrix - CGBMV 4-10 

Multiplies a complex vector by a complex 

general matrix - CGEMV 4-18 

Multiplies a complex vector by a complex 

Hermitian band matrix - CHBMV 4-24 

Multiplies a complex vector by a complex 

Hermitian matrix - CHEM V 4-29 

Multiplies a complex vector by a complex 

triangular band matrix - CTBMV 4-50 

Multiplies a complex vector by a complex 

triangular matrix - CTRMV , ...4-58 



Multiplies a matrix by a row vector and adds 

the result to another row vector - 

SXMPY 4-156 

Multiplies a real general matrix by a real 

general matrix - SGEMM 4-108 

Multiplies a real general matrix by a real 

general matrix using Strassen's 

algorithm - SGEMMS 4-1 10 

Multiplies a real general matrix by a real 

symmetric matrix - SSYMM 4-135 

Multiplies a real general matrix by a real 

triangular matrix - STRMM.. 4-150 

Multiplies a real vector by a real general 

band matrix - SGBMV 4-106 

Multiplies a real vector by a real general 

matrix -SGEMV 4-113 

Multiplies a real vector by a real symmetric 

band matrix - SSBMV 4-131 

Multiplies a real vector by a real symmetric 

matrix - SSYMV 4-138 

Multiplies a real vector by a real triangular 

band matrix - STBMV 4-146 

Multiplies a real vector by a real triangular 

matrix -STRMV 4-152 

multiplying matrices - MXM 4-86 

multiplying matrices - MXMA 4-88 

multitasking - BUFPRINT 14-9 

multitasking - EVASGN 14-14 

multitasking - EVCLEAR 14-15 

multitasking - EVPOST 14-16 

multitasking - EVREL 14-17 

multitasking - EVWATT 14-19 

multitasking - LOCKON 14-23 

multitasking - LOCKREL 14-24 

multitasking - TSKSTART 14-28 

multitasking - TSKWAIT 14-32 

multitasking add entries to trace buffer - 

BUFUSER 14-13 

multitasking assign lock - LOCKASGN 14-21 

multitasking barrier - BARASGN .14-5 

multitasking barrier - BARREL ? 14-6 

multitasking clear lock - LOCKOFF 14-22 

multitasking dump - BUFDUMP 14-8 

multitasking dump - BUFPRINT 14-9 

multitasking event test - EVTEST 14-18 

multitasking modify library scheduler 

parameters - TSKTUNE 14-30 

multitasking routines introduction - INTRO 14-1 

multitasking synchronizes task at barrier - 

BARSYNC 14-7 

multitasking test for task - TSKTEST 14-29 

multitasking test lock - LOCKTEST 14-25 

multitasking tuning - BUFTUNE 14-10 

MVC - Moves characters from one memory area 

to another , 10-6 

MXM - Computes matrix-times-matrix product 

(unit increments) 4-86 

MXMA - Computes matrix-times-matrix product 

(arbitrary increments) 4-88 

MXV - Computes matrix-times-vector product 

(unit increments) , 4-92 

MX VA - Computes matrix-times-vector product 

(arbitrary increments) 4-94 
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NACSED - Returns the edition of a 

previously-accessed permanent dataset 17-37 

name-UNAME 18-8 

name of job - JNAME 17-31 

NAMELJST delimiter change - WNL.. 12-73 

NAMEL1ST error unit - RNLECHO 12-55 

NAMELIST input changes - RNL 12-54 

NAMELIST record skip - RNLSKIP 12-56 

NAMEUST variable on new line - WNLLINE 12-74 

natural logarithm - ALOG 2-13 

nearest integer - N1NT 2-60 

nearest integer search - NINT 2-60 

nearest number search - ANINT ***2-19 

nearest whole number - ANINT 2-19 

NEQV - Computes logical difference 2-58 

NINT - Finds nearest integer 2-60 

NORERUN - Declares a job rerunnable/not 

Terminable 17-42 

normal I/O continuing - CONTPIO 12-30 

normalized number small and large - SMACH 17-46 

not rerunnable job - RERUN 17-42 

notification at EOV - ENDSP 12-31 

notify of EOV - S VOLPRC 12-65 

null to trailing blank conversion - RBN. 8-15 

number of arguments -IARGC 17-26 

number of characters in string - TRIMLEN 10-7 

NUMBLKS - Returns the current size of a 

dataset in 5 12- word blocks 13-9 

numerals to integer conversion - CHCONV 8-10 

octal from binary conversion - B20CT 8-5 

one bits count - POPCNT 2-63 

open AQIO dataset - AQOPEN 12-12 

open AQIO dataset - AQOPENDV .....12-13 

open dataset - OPENMS 12-42 

open random access - WOPEN .....12-76 

open random access - WOPENU 12-78 

open unbuffered dataset - WOPENU ..12-78 

OPENDR - Opens a local dataset as a random 

access dataset 12-42 

OPENMS - Opens a local dataset as a random 

access dataset 12-42 

Opens a dataset or Hie for asynchronous 

queued I/O - AQOPEN 12-12 

Opens a dataset or file for asynchronous 

queued I/O, allowing user to specify 



dataset size and physical location - AQOPENDV. 12- 13 



Opens a local dataset as a random access 

dataset - OPENMS 12-42 

Opens a word-addressable, random-access 

dataset - WOPEN 12-76 

Opens a word- addressable, random-access 

dataset, unbuffered - WOPENU 12-78 

operating system (COS) request - SYSTEM 17-48 

operating system name - UNAME .....18-8 

OPFTLT - Solves Weiner-Levinson linear 

equations 4-98 

option letter - GETOFT 18-5 

OR - Computes logical sum 2-61 

ordered array search - OSRCHL. 6-20 

ordered array search - OSRCHM , 6-21 

ORDERS - Sorts using internal, fixed-length 

record sort 7-2 

orthogonal plane rotation - SROT. 4-121 



OSRCHF - Searches an ordered array and 

returns index of the first location that 

contains the target 6-20 

OSRCHI - Searches an ordered array and 

returns index of the first location that 

contains the target , 6-20 

OSRCHM - Searches an ordered integer array 

and returns index of the first location 

that is equal to the integer target 6-21 

Output a value in an argument as blank - FSUP 12-33 

output characters - WRITEC 12-81 

output data - WRITE 12-80 

output Exchange Package - FXP 16-6 

output format control - WNL 12-73 

output line length - WNLLONG ; 12-75 

ouiput unit NAMELIST - RNLECHO 12-55 

output value change - FSUP 12-33 

output wait for end - WAITMS 12-69 

OVERLAY - Loads an overlay and transfers 

control to the overlay entry point. 17-38 

overlay load - OVERLAY 17-38 

P32 - Packs/unpacks 32-bit words into or from 

Cray 64-bit words 9-3 

P6460 - Packs/unpacks 60-bit words into or 

from Cray 64-bit words .9-4 

PACK - Compresses stored data 9-2 

pack 64 into 60 bits - P6460 9-4 

pack data -PACK 9-2 

pack from 64 to 32 bits - P32 .9-3 

packed decimal conversion - USPCTC 8-24 

packed decimal to integer conversion - USPCTC 8-24 

packing routines introduction - INTRO ..9*1 

Packs/unpacks 32-bit words into or from Cray 

64-bit words -P32 9-3 

Packs/unpacks 60-bit words into or from Cray 

64-bit words - P6460 9-4 

page length - GETLPP 17-23 

parameters - GETPARAM 17-24 

parameters process - PPL 17-39 

parity bit population - POPPAR 2-64 

partial products problem - RECPP 4-99 

partial record read - READC , 12-50 

partial summation problem - RECPS 4-100 

partial-record mode - WRITE 12-80 

partial-record mode - WRITEC 12-81 

partial-record read - READ 12-49 

Pascal snapshot dump - SYMDUMP 16-16 

PDUMP - Dumps memory to $OUT 16-4 

PERF - Provides an interface to the hardware 

performance monitor 16-9 

performance monitor interface - PERF 16-9 

Performs 64-bit integer divide - LDIV 2-51 

Performs a left circular shift - SHIFT 2-70 

Performs a left shift with zero fill - SHIFTL 2-72 

Performs aright shift with zero fill - SHIFTR 2-74 

Performs conjugated rank 1 update of a 

complex general matrix - CGERC 4-20 

Performs double-precision arithmetic - 

DBLJ>REC 2-37 

Performs Hermitian rank 1 update of a complex 

Hermitian matrix - CHER 4-31 

Performs Hermitian rank 2 update of a complex 

Hermitian matrix - CHER2 4-33 
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Performs Heimitian rank 2k update of a 

complex Heimitian matrix - CHER2K 4-35 

Performs Heimitian rank k update of a complex 

Heimitian matrix - CHERK 4-38 

Performs rank 1 update of a real general 

matrix - SGER 4-114 

Performs sparse vector operations - SPDOT 4-120 

Performs symmetric rank 1 update of a real 

symmetric matrix - SSYR 4-139 

Performs symmetric rank 2 update of a real 

symmetric matrix - SSYR2 4-140 

Performs symmetric rank 2k update of a 

complex symmetric matrix - CSYR2K 4-45 

Performs symmetric rank 2k update of a real 

symmetric matrix - SSYR2K 4-141 

Performs symmetric rank k update of a complex 

symmetric matrix - CSYRK 4-48 

Performs symmetric rank k update of a real 

symmetric matrix - SSYRK.... , 4-144 

Performs triple-precision arithmetic - TADD 2-84 

Performs unconjugated rank 1 update of a 

complex general matrix - CGERU 4-22 

Permanently disables/enables bidirectional 

memory transfers - CLEARBTS 17-10 

permit interrupts - CLEARFI . 17-1 1 

permit interrupts - CLEARFIS 1742 

Places an octal ASCII representation of a 

Cray word into a character area - B20CT 8-5 

plane rotation - CROT 4-40 

plane rotation - CROTG 4-41 

plane rotation - SROTG 4-122 

plane rotation - SROTM 4-124 

plane rotation - SROTMG 4-126 

Polish Table - CEXPR - 17-8 

POPCNT - Counts number of bits set to 1 2-63 

POPPAR - Computes bit population parity 2-64 

population count • POPCNT.... 2-63 

population parity - POPPAR 2-64 

position at EOD - SKIPD 13-10 

position at tape block - SETTP 12-59 

position information - GETTP 12-36 

Positions a blocked dataset at EOD - SKIPD 13-10 

Positions a dataset after the previous EOF - 

BACKFILE 13-3 

Positions a tape dataset or file - SETTP 12-59 

positive difference - DIM .2-41 

post multitasking - EVPOST 14-16 

post multitasking events - EVPOST 14-16 

Posts an event and returns control to the 

calling task - EVPOST 14-16 

pow - Raises base value to a power 2-65 

power function - POWER 2-65 

PPL - Processes keywords of a directive 17-39 

preset table space - TMPTS 1 1-19 

Presets table space - TMPTS 1 1-19 

print Exchange Package - FXP 16-6 

print Exchange Package - XPFMT 16-22 

Prints a memory dump to a specified dataset - 

CRAYDUMP .16-3 

PROCBOV - Allows special processing at 

beginning-of-volume 12-44 

PROCEOV - Begins special processing at 

end-of-volume (EOV) (obsolete) 12-45 

process parameters - PPL 17-39 

Processes keywords of a directive - PPL 17-39 



produce symbolic dump - SYMDEBUG 16-14 

Produces a printable image of an Exchange 

Package - XPFMT 16-22 

Produces a snapshot dump of a running program 

-SYMDUMP 16-16 

Produces a symbolic dump - SYMDEBUG 16-14 

product logical - AND ..2-17 

program execution resume for I/O - AQRECALL 12-17 

program exit - EXIT 17-21 

program IOS channel - DRIVER 17-15 

program load -LGO 17-33 

program synchronize with tape dataset - SYNCH .12-67 

programming aid routines introduction - INTRO 16-1 

Programs a Cray channel on an I/O Subsystem 

(IOS) - DRIVER 17-15 

prohibit interrupts - CLEARFI 17-1 1 

prohibit interrupts - CLEARFIS ....17-12 

Provides an interface to the hardware 

performance monitor -PERF 16-9 

Provides user control of output - WNL... 12-73 

pseudo-random number - RAN 2-66 

PUTBYT - Replaces a byte in a variable or an 

array 10-2 

PUTWA - Writes to a word-addressable, 

random-access dataset ... . 12-46 

PUTWAU - Writes to a word-addressable, 

random-access dataset, unbuffered ....12*47 

QR UNPACK . .4-79 

queue read request - AQREAD ....12-15 

queue write request - AQWRTTE 12-22 

Queues a simple or compound asynchronous I/O 

read request - AQREAD 12-15 

Queues a simple or compound asynchronous I/O 

write - AQWRTTE ..12-22 

quit program - EXIT 17-21 

Raises base value to a power • POWER 2-65 

random access and asynchronous I/O - ASYNCMS 12-24 

random access buffering - FINDMS 12-32 

random access close - CLOSMS 12-28 

random access close - WCLOSE .12-71 

random access close - WCLOSEU 12-72 

random access I/O - AQOPEN 12-12 

random access I/O - AQOPENDV 12-13 

random access I/O check - CHECKMS 12-25 

random access I/O mode - SYNCMS 12-68 

random access open - OPENMS ..12-42 

random access open - WOPEN... 12-76 

random access open - WOPENU 12-78 

random access read - GETWA 12-38 

random access read - GETWAU 12-40 

random access read - READMS 12-52 

random access synchronous - SYNCMS 12-68 

random access write - WRITMS..,. 12-83 

random -access write - PUTWA 12-46 

random-access write - PUTWAU 12-47 

RANF - Computes pseudo-random numbers 2-66 

RANGET - Computes pseudo-random numbers ..2-66 

rankl-CGERC 4-20 

rank 1 - CGERU 4-22 

rank 1 - CHER 4-31 

rank 1 - SGER 4-114 

rank 1 - SSYR 4-139 

rank 1 update - SGER ......4-1 14 
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rank2-CHER2 , .....4-33 

rank 2 -SS YR2 4-140 

rank2k-CHER2K 4-35 

rank 2k - CSYR2K. 4-45 

rank2k-SSYR2K 4-141 

rankk -CHERK 4-38 

rankk-CSYRK 4-48 

rankk-SSYRK .4444 

RANSET - Computes pseud o -random numbers 2-66 

RBN - Converts trailing blanks to nulls and 

vice versa 8-15 

RCFFT2 - Applies a real-to -complex Fast 

Fourier Transform (FFT) .5-7 

READ - Reads words, full or partial record 

modes 12-49 

read asynchronously - AQREAD . 12-15 

read characters - READC 12-50 

read data - GETWA 12-38 

read data - GETWAU 12-40 

read ibm words - READffiM 12-5 1 

read random access - READMS 12-52 

read record - FINDMS 12-32 

read words - READ 12-49 

READC - Reads characters, full or partial 

record mode 12-50 

READCP - Reads characters, full or partial 

record mode ..♦ 12-50 

READDR - Reads a record from a random access 

dataset 12-52 

READBBM - Reads two IBM 32-bit floating-point 

words 12-51 

READMS - Reads a record from a random access 

dataset 12-52 

READP - Reads words, full or partial record 

modes 12-49 

Reads a record from a random access dataset 

- READMS 12-52 

Reads characters, full or partial record mode 

- READC 12-50 

Reads record into data buffers - FINDMS 12-32 

Reads two IBM 32-bit floating-point words - 

READIBM.... 12-51 

Reads words, full or partial record modes - 

READ 12-49 

REAL - Converts to type real 2-68 

real approximation of double-precision number 

- SNGLR 2-81 

real array element - ISRCHFLT 6-14 

real array elements - WHENEQ 6-22 

real array elements - WHENFLT 6-23 

real array search - WHENFLT 6-23 

real cluster - CLUSFLT ..6-6 

real general band matrix - SGBMV 4-106 

real general matrix - SGEMM 4408 

real general matrix - SGEMMS ,.4-110 

real general matrix - SGEMV .4-113 

real general matrix - SGER 4-114 

real general matrix - SSYMM .4-135 

real general matrix - STRMM.... 4-150 

real product - DOT 4-64 

real symmetric band matrix - SSBMV 4-131 

real symmetric matrix - SSYR2K 4-141 

real symmetric matrix - SSYRK ..4-144 

real symmetric matrix - SSYMM 4-135 

real symmetric matrix * SSYMV 4-138 
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real symmetric matrix - SSYR 4-139 

real symmetric matrix - SSYR2 4-140 

real time value - RTC 15-6 

real to complex FFT - RCFFT2 5-7 

real triangular band matrix - STBMV 4-146 

real triangular banded system of linear 

equations - STBSV 4-148 

real triangular matrix - STRMM 4-150 

real triangular matrix - STRMV 4-152 

real triangular system of equations - STRSM 4-153 

real triangular system of linear equations - 

STRSV 4-155 

real truncation - AINT 2-12 

real vector - SCAL 4-103 

real vector - SCOPY 4-105 

real vector - SGBMV 4-106 

real vector - SGEMV 4-113 

real vector - SSBMV 4-131 

real vector - SSYMV 4-138 

real vector - STBMV ..4-146 

real vector - STRMV 4-152 

real vector addition - SAXPY 4-102 

real vector addition - SSUM 4-133 

real vector exchange - SS WAP 4-134 

real-time to time-stamp -TSMT 15-11 

real-to-complex Fast Fourier transform 

(multiple input vectors) - RFFTMLT 5-8 

record read random access - READMS .. 12-52 

record skip -SKIPR 13-11 

record skip NAMELJST - RNLSKIP 12-56 

RECPP - Solves a partial products problem 4-99 

RECPS - Solves a partial summation problem 4-100 

reduce dataset memory - STINDX 12-63 

reducing execution time - EISPACK 4-65 

register to $OUT copy - SNAP... 16-13 

Registers the arrival of a task at a barrier 

-BARSYNC 14-7 

release - UNAME 18-8 

release a multitasking event - EVREL 14-17 

release a multitasking lock - LOCKREL 14-24 

release identifier - BARREL 14-6 

release identifier assigned to lock - LOCKREL 14-24 

release lock - LOCKREL 14-24 

release multitasking barrier identifier - 

BARREL 14-6 

release variable assigned an event - EVREL 14-17 

release version - UNAME ♦ 18-8 

Releases the identifier assigned to a barrier 

-BARREL 14-6 

Releases the identifier assigned to a lock - 

LOCKREL 14-24 

Releases the identifier assigned to the task 

- EVREL 14-17 

remainder - MOD 2-56 

REMARK - Enters a message in the user and 

system log files 17-40 

REMARK2 - Enters a message in the user and 

system log files 17*40 

REMARKF - Enters a formatted message in the 

user and system logfiles 17-41 

replace byte - BYT 10-2 

replacement character NAMEUST - WNL 12-73 

Replaces a byte in a variable or an array - 

BYT 10-2 

report table statistics - TMAMU....... 11-14 
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Reports table management operation statistics 

-TMAMU 11-14 

reprieve routine - SETRPV 17-45 

request from COS - SYSTEM 17-48 

request memory - TMMEM 11-16 

Requests abort - ERREXIT 17-20 

Requests abort with traceback - ABORT 17-5 

Requests additional memory - TMMEM, 11-16 

Requests notification at the end of a tape 

volume - ENDSP 12-31 

Requests notification at the end of a tape 

volume - SETSP 12-58 

RERUN - Declares a job reruimable/not 

rerunnable 17-42 

rerunnable job declaration - RERUN 17-42 

resume program during AQIO request - AQRECALL..12-17 

retrieve JCL symbol - JSYMSET. .....17-32 

retrieve seed - RAN .....2-66 

Retrieves user identifier specified in task 

control array - TSKVALUE. 14-31 

return bit mask - MASK 2-55 

return end of file status - EOF 13-7 

return Fortran argument - GETARG 17-22 

Return Fortran command-line argument - GETARG ....17-22 
return identifier in task control array - 

TSKVALUE 14-31 

return location of variable in memory - LOC 17-34 

return memory to heap - HPDEALLC 1 1-7 

return message to user and system - REMARK 17-40 

return message to user and system - REMARKF 17-41 

return number - TRIMLEN 10-7 

return page length - GETLPP 17-23 

return part of heap - HPSHRINK 1 1-10 

Return real-time clock values - RTC 15-6 

return value - RTC 15-6 

Returns a bit mask - MASK 2-55 

Returns a block of memory to the list of 

available space -HPDEALLC 11-7 

Returns a value indicating whether the 

indicated task exists - TSKTEST.... 14-29 

Returns an unused portion of heap to the 

operating system - HPSHRINK 1 1-10 

Returns closest real approximation to double 

precision - SNGLR 2-81 

Returns elapsed CPU time - SECOND .15-7 

Returns elapsed CPU time for a calling task 

during a multitasked program - TSECND 14-27 

Returns elapsed wall-clock time since the 

call to TIMEF - TIMEF 15-8 

Returns EOF and EOD status - 10STAT 13-8 

Returns information on current level of 

calling sequence - TRBKLVL 16-21 

Returns integer ceiling of a rational number 

-ICEIL 17-27 

Returns lines per page - GETLPP 17-23 

Returns machine cycle time - JCCYCL... 14-20 

Returns machine epsilon, small/large 

normalized numbers - SMACH 17-46 

Returns memory address of variable or array - 

LOC... 17-34 

Returns name of the caller - GETNAMEQ 16-7 

Returns number of command-line arguments - 

IARGC 17-26 



Returns number of occurrences of object in a 

vector -IILZ .......6-8 

Returns real or integer value EOF status - EOF 13-7 

Returns statistics about the heap - IHPSTAT 11-12 

Returns the CPU time (in floating-point 

seconds) - TREMA1N 15-9 

Returns the current date and the current 

Julian date - DATE 15-4 

Returns the current size of a dataset in 

5 12-word blocks - NUMBLKS 13-9 

Returns the current system-clock time - CLOCK 15-3 

Returns the cycles charged to a job - IGETSEC 16-8 

Returns the edition of a previously-accessed 

permanent dataset - NACSED 17-37 

Returns the Job Accounting Table (JAT) - 

ACTTABLE 17-6 

Returns the job name - JNAME 17-31 

Returns the largest of all arguments - MAX 6-18 

Returns the length of a heap block - IHPLEN 11-1 1 

Returns the maximum number of logical 

CPUs available - MAXLCPUS 14-26 

Returns the number of characters in a string 

- TRIMLEN 10-7 

Returns the smallest of all arguments - MIN 6-19 

Returns time-stamp units in specified 

standard time units - UNITTS 15-12 

Returns value for environment name - GETENV..........18-4 

Reverse Polish Table - CEXPR .17-8 

RFFTMLT - Applies complex-to-real and 

real- to-complex Fast Fourier Transforms (FFT) 

on multiple input vectors 5-8 

right shift - SHIFTR 2-74 

RNB - Converts trailing blanks to nulls and 

vice versa 8-15 

RNLCOMM - Adds or deletes characters from the 

set of characters recognized by the 

NAMEliST 12-54 

RNLDELM - Adds or deletes characters from the 

set of characters recognized by the 

NAMELIST 12-54 

RNLECHO - Specifies output unit for NAMELIST 

error messages 12-55 

RNLFLAG - Adds or deletes characters from the 

set of characters recognized by the 

NAMEUST 12-54 

RNLREP - Adds or deletes characters from the 

set of characters recognized by the 

NAMELIST 12-54 

RNLSEP - Adds or deletes characters from the 

set of characters recognized by the 

NAMEUST 12-54 

RNLSKIP - Takes appropriate action when an 

undesired NAMEUST 12-56 

RNLTYPE - Determines action if a type 

mismatch occurs across the equal sign on an 

input record 12-57 

row vector - SXMPY 4-156 

RTC - Return real-time clock values 15-6 

RTOI - Raises base value to a power 2-65 

RTOR - Raises base value to a power 2-65 

SASUM - Sums the absolute value of elements 

in a vector 4-101 
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S AXPY - Adds a scalar multiple of a real or 

complex vector 4-102 

scalar multiple addition - SAXPY ... 4-102 

scale - SCAL 4-103 

Scales a real or complex vector - SCAL 4-103 

scaling a complex vector - SCAL 4-103 

scaling a real vector - SCAL 4-103 

SCASUM - Sums the absolute value of elements 

in a vector ....4-101 

SCATTER - Scatters a vector into another 

vector 4-104 

scattering vectors - SCATTER 4-104 

Scatters a vector into another vector - 

SCATTER 4-104 

SCNRM2 - Computes the Euclidean norm of a 

vector 4-116 

SCOPY - Copies a real or complex vector into 

another vector 4-105 

screen (CRT) updating - CURSES 19-2 

SDACCESS - Allows a program to access 

datasets in the System Directory 3-8 

SDOT - Computes a dot product (inner product) 

of two real or complex vectors 4-64 

search environment list for value - GETENV 18-4 

search for DSP - GETDSP.. 3-6 

search for string - FINDCH .10-3 

search routines introduction - INTRO 6-1 

search table - TMMSC 11-17 

search table - TMSRC 11-20 

search vector table - TMVSC 11-21 

Searches a variable or an array for an 

occurrence of a character string - FINDCH 10-3 

Searches a vector table for the search 

argument - TMVSC 11-21 

Searches an ordered array and returns index 

of the first location that contains the 

target - OSRCHI 6-20 

Searches an ordered integer array and returns 

index of the first location that is 

equal to the integer target - OSRCHM 6-21 

Searches for a Dataset Parameter Table (DSP) 

- GETDSP 3-6 

Searches for the maximum or minimum value in 

atable-INFLMAX ..6-9 

Searches for the maximum or minimum value in 

an integer vector - INTMAX 6-10 

Searches the table with a mask to locate a 

specific field - TMMSC 1 1-17 

Searches the table with an optional mask to 

locate a specific field within an entry 

and an offset - TMSRC 1 1-20 

Searches vector for logical match - ISRCHMLT 6-17 

SECOND - Returns elapsed CPU time 15-7 

second-order linear recurrences - SOLR 4-117 

sector skip - SKIPU 13-13 

SEEK - Synchronously and asynchronously reads 

data 12-38 

sense switch test - SS WITCH 17-47 

SENSEBT - Determines whether bidirectional 

memory transfer is enabled or disabled 17-43 

SENSEFI - Determines if floating-point 

interrupts are permitted or prohibited 17-44 

separator NAMELIST change - WNL 12-73 

set a multitasking event - EVASGN 14-14 

set a multitasking lock - LOCKON 14-23 



set floating-point interrupts - CLEARFI 17-11 

set floating-point interrupts - CLEARFIS 17-12 

set I/O mode - ASYNCMS 12-24 

Set I/O mode for random access routines to 

asynchronous - ASYNCMS 12-24 

set lock - LOCKON 14-23 

set seed -RAN 2-66 

SETBT - Temporarily disables/enables 

bidirectional memory transfers 17-9 

SETBTS - Permanently disables/enables 

bidirectional memory transfers 17-10 

SETFI - Temporarily prohibits/permits 

floating-point interrupts 17-1 1 

SETFIS - Temporarily prohibits/permits 

floating-point interrupts for a job 17-12 

SETPLIMQ - Initiates detailed Gracing of 

every call and return. 16-12 

SETRPV - Conditionally transfers control to a 

specified routine 17-45 

Sets a lock and returns control to the 

calling task - LOCKON 14-23 

Sets I/O mode for random access routines to 

synchronous - SYNCMS 12-68 

SETSP - Requests notification at the end of a 

tape volume 12-58 

SETTP - Positions a tape dataset or file 12-59 

SGBM V - Multiplies a real vector by a real 

general band matrix 4-106 

SGEMM - Multiplies a real general matrix by 

a real general matrix..... .....4-108 

SGEMMS - Multiplies a real general matrix by 

a real general matrix using Strassen's 

algorithm 4-110 

SGEM V - Multiplies a real vector by a real 

general matrix 4-1 13 

SGER - Performs rank 1 update of a real 

general matrix 4-1 14 

shell command execute - ISHELL... 17-30 

SHIFT - Performs a left circular shift 2-70 

shift circular - SHIFT 2-70 

shift left -SHIFTL.... 2-72 

shift right - SHIFTR 2-74 

SHIFTL - Performs a left shift with zero fill .2-72 

SHIFTR - Performs a right shift with zero fill 2-74 

shrink heap - HPSHRINK...... 11-10 

sign -SIGN 2-76 

SIGN - Transfers sign of numbers ......2-76 

sign transfer - SIGN 2-76 

SIN - Computes the sine 2-77 

sin - Computes the sine . 2-77 

sine (hyperbolic) - SINH 2-79 

sine - SIN 2-77 

single-precision - USDCIT 8-20 

single-precision approximation of 

double-precision number - SNGLR 2-81 

Single-precision EISPACK routines - EISPACK 4-65 

Single-precision real and complex UNPACK 

routines - UNPACK 4-79 

singular value decomposition - EISPACK 4-65 

singular value decompositions - L1NPACK .....4-79 

SINH - Computes hyperbolic sine 2-79 

sinh - Computes hyperbolic sine 2-79 

size of dataset - NUMBLKS 13-9 

skip bad data - SKIPBAD 12-61 

skip dataset - SKIPD 13-10 
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skip files -SKIPR 13-11 

skip record NAMELIST - RNLSKIP 12-56 

skip records - SKIPR 13-11 

Skip records or files - SKIPR 13-11 

skip sectors - SKIPU 1343 

SKJPBAD - Skips bad data 12-61 

SKIPD - Positions a blocked dataset at EOD 13-10 

SKIPF - Skip records or files 13-11 

SKIPR - Skip records or files 13-1 1 

Skips a specified number of sectors in a 

dataset -SKIPU 13-13 

Skips bad data - SKIPBAD 12-61 

SKIPU - Skips a specified number of sectors 

in a dataset 13-13 

SMACH - Returns machine epsilon, small/large 

normalized numbers .17-46 

smallest argument - MIN 6-19 

smallest normalized number - SMACH 17-46 

SMXPY - Multiplies a column vector by a 

matrix and adds the result to another 

column vector 4-1 15 

SNAP - Copies current register contents to 

$OUT 16-13 

snapshot dump - SYMDUMP 16-16 

SNGL - Converts to type real .2-68 

SNGLR - Returns closest real approximation to 

double precision ,2-8 1 

SNRM2 - Computes the Euclidean norm of a 

vector . 4-116 

SOLR - Solves second-order linear recurrences .4-117 

SOLR3 - Solves second-order linear 

recurrences 4-1 17 

SOLRN - Solves second-order linear recurrences 4-117 

Solves a complex triangular banded system of 

equations - CTBSV 4-53 

Solves a complex triangular system of 

equations - CTRSV 4-62 

Solves a complex triangular system of 

equations with multiple right-hand sides - 

CTRSM 4-60 

Solves a partial products problem - RECPP 4*99 

Solves a partial summation problem - RECPS 4-100 

Solves a real triangular banded system of 

linear equations - STBSV 4-148 

Solves a real triangular system of equations 

with multiple right-hand sides - STRSM 4-153 

Solves a real triangular system of linear 

equations - STRSV 4-155 

Solves first-order linear recurrence with 

constant coefficient - FOLRC ,. .4-75 

Solves first-order linear recurrences - FOLR 4-71 

Solves first-order linear recurrences without 

overwriting operand vector - FOLR2 4-73 

Solves for last term of a first-order linear 

recurrence - FOLRNP 4-77 

Solves for the last term of first-order 

linear recurrence -FOLRN 4-76 

Solves second-order linear recurrences - SOLR 4-1 17 

Solves systems of linear equations by 

inverting a square matrix - MINV 4-82 

Solves Weiner-Levinson linear equations - 

OPHLT 4-98 

sorting routines introduction - INTRO 7-1 



Sorts using internal, fixed-length recard 

sort - ORDERS 7-2 

source vector - GATHER 4-78 

space for table -TMPTS 11-19 

sparse dot product - SPDOT 4-120 

sparse inner product - SPDOT 4-120 

sparse vector - SPDOT 4-120 

SPAXPY - Performs sparse vector operations 4-120 

SPDOT - Performs sparse vector operations 4-120 

special processing at end of tape - SETSP...... 12-58 

Specifies output unit for NAMELIST error 

messages -RNLECHO.... 12-55 

SQRT - Computes square root 2-82 

sqrt - Computes square root , 2-82 

square matrix - MINV ...4-82 

square root - SQRT 2-82 

SROT - Applies an orthogonal plane rotation 4-121 

SROTG - Constructs a Givens plane rotation 4-122 

SROTM - Applies a modified Givens plane 

rotation 4-124 

SROTMG - Constructs a modified Givens plane 

rotation 4-126 

SSBMV - Multiplies a real vector by a real 

symmetric band matrix 4-131 

S SC AL - Scales a real or complex vector.., ....4-103 

SSUM - Sums the elements of a real or complex 

vector. , 4-133 

SSWAP - Swaps two real or complex arrays 4-134 

SS WITCH - Tests the sense switch ...17-47 

SS YMM - Multiplies a real general matrix by a 

real symmetric matrix 4-135 

SS YMV - Multiplies a real vector by a real 

symmetric matrix 4-138 

SSYR - Performs symmetric rank 1 update of a 

real symmetric matrix 4-139 

SSYR2 - Performs symmetric rank 2 update of a 

real symmetric matrix 4-140 

SS YR2K - Performs symmetric rank 2k update of 

a real symmetric matrix 4-141 

SS YRK - Performs symmetric rank k update of a 

real symmetric matrix 4-144 

stamp time to ASCII -TSDT 15-10 

standard time - UNTTTS 15-12 

start a task - TSKSTART 14-28 

STARTSP - Begins user EOV and BOV processing 12-62 

statistics about heap - IHPSTAT 1 1-12 

statistics on performance - PERF 16-9 

statistics table management - TMAMU.,.. 11-14 

status of AQIO requests - AQSTAT 12-19 

status of EOF and EOD - IOSTAT 13-8 

status of I/O - CHECKMS 12-25 

STBM V - Multiplies a real vector by a real 

triangular band matrix , 4-146 

STBSV - Solves a real triangular banded 

system of linear equations , „ , 4-148 

stderr message from user - REMARK 17-40 

stderr message from user - REMARKF 17-41 

STINDR - Allows an index to be used as the 

current index 12-63 

STTNDX - Allows an index to be used as the 

current index 12-63 

stop Fortran program - EXIT .17-21 

Stops the processing of asynchronous queued 

I/O requests -AQSTOP ..12-20 

storage request -TMMEM 11-16 
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Strassen's algorithm - CGEMMS 4-15 

Strassen's algorithm - SGEMMS 4-110 

string characters - TRIMLEN 10-7 

string comparison - KOMSTR 10-4 

string comparison - LGE 2-54 

string search - FENDCH , 10-3 

string translation - TR ......8-16 

STRMM - Multiplies a real general matrix by a 

real triangular matrix .4-150 

STRMOV - Moves bytes or bits from one 

variable or array to another 10-5 

STRM V - Multiplies a real vector by a real 

triangular matrix ♦ 4-152 

STRSM - Solves a real triangular system of 

equations with multiple right-hand sides 4-153 

STRSV - Solves a real triangular system of 

linear equations ..4-155 

subindex creation - STINDX ...12-63 

subroutine listing - TRBK 16-20 

subtract memory - MEMORY 17-35 

subtraction (double-precision) - DBL_PREC 2-37 

subtraction (triple-precision) - TADD * 2-84 

sum (logical) - OR .2-61 

Sums the absolute value of elements in a 

vector - SASUM 4-101 

Sums the elements of a real or complex vector 

-SSUM.. , 4-133 

suspend for AQIO requests - AQWATT 12-21 

suspend job - ERECALL 17-18 

SVOLPRC - Initializes/terminates special 

BOV/EOV processing (obsolete) 12-65 

swapping vectors - SSWAP 4-134 

Swaps two real or complex arrays - SSWAP 4-134 

switch tape volume - S WITCH V 12-66 

switch test sense - SSWTTCH 17-47 

Switches tape volume - S WITCH V 12-66 

SWITCHV - Switches tape volume 12-66 

SXMPY - Multiplies a matrix by a row vector 

and adds the result to another row 

vector. 4-156 

symbol JCL - JSYMSET 17-32 

symbolic dump program - SYMDEBUG 16-14 

SYMDEBUG - Produces a symbolic dump 16-14 

S YMDUMP - Produces a snapshot dump of a 

iitnning program 16-16 

symmetric coefficient - FILTERS 4-70 

symmetric rank 1 update - SSYR 4-139 

symmetric rank 2 update - SSYR2 4-140 

symmetric rank 2k update - CSYR2K 4-45 

symmetric rank 2k update - SSYR2K 4-141 

symmetric rank k update - CS YRK 4-48 

symmetric rank k update - SS YRK 4-144 

symmetric vectors - FILTERS 4-70 

SYNCDR - Sets I/O mode for random access 

routines to synchronous ..12-68 

SYNCH - Synchronizes the program and an 

opened tape dataset 12-67 

synchronize I/O mode - SYNCMS 12-68 

synchronize multitasking - BARSYNC 14-7 

synchronize program and tape dataset - SYNCH 12-67 

Synchronizes the program and an opened tape 

dataset - SYNCH 12-67 

synchronous read - GETWA. 12-38 



Synchronously and asynchronously reads data 

- GETWA 12-38 

SYNCMS - Sets I/O mode for random access 

routines to synchronous 12-68 

system - CLOCK 15-3 

SYSTEM - Makes requests of the operating 

system 17-48 

system clock time - CLOCK 15-3 

system directory access - SDACCESS 3-8 

system interface routines introduction - INTRO 17-1 

system of equations - CTBSV ...4-53 

system of equations - CTRSM 4-60 

system of equations - CTRSV 4-62 

system of equations - STRSM 4-153 

system of linear equations - MINV ....4-82 

system of linear equations - STBSV 4-148 

table, add word to - TMADW 1 1-13 

table management statistics - TMAMU 11-14 

table search - TMMSC 11-17 

table search - TMSRC 11-20 

table search vector - TMVSC 1 1-21 

table space allocation - TMATS 11-15 

table space preset - TMPTS 1 1-19 

TADD - Performs triple-precision arithmetic 2-84 

Takes appropriate action when an undesired 

NAMEUST - RNLSKIP... 12-56 

TAN - Computes tangent 2-85 

tan - Computes tangent 2-85 

tangent (hyperbolic) - TANH 2-87 

tangent - TAN 2-85 

TANH - Computes hyperbolic tangent 2-87 

tanh - Computes hyperbolic tangent 2-87 

tape block position - SETTP 12-59 

tape BOV processing - PROCBOV 12-44 

tape data accepting - ACPTBAD 12-9 

tape dataset position - GETTP 12-36 

tape dataset positioning - GETPOS 12-34 

tape dataset synchronize with program - SYNCH 12-67 

tape EOV and BOV processing - STARTS P 12-62 

tape EOV processing - PROCEOV 12-45 

tape EOV processing - CLOSEV 12-27 

tape EOV processing - SVOLPRC 12-65 

tape file position - GETTP 12-36 

tape I/O status - CHECKTP ....,12-26 

tape notification at EOV - ENDSP 12-31 

tape processing at end - SETSP 12-58 

tape skip data - SKJPBAD 12*61 

tape volume switch - SWITCHV 12-66 

task identifier return value - TSKVALUE 14-31 

TASS - Performs triple-precision arithmetic 2-84 

TDIV - Performs triple-precision arithmetic 2-84 

TDSS - Performs triple-precision arithmetic 2-84 

Temporarily disables/enables bidirectional 

memory transfers - CLEARBT 17-9 

Temporarily prohibits/permits floating-point 

interrupts - CLEARFI 17-1 1 

Temporarily prohibits/permits floating-point 

interrupts for a job - CLEARFIS 17-12 

termcap routines - CURSES 19-2 

terminate dataset - EODW 13-6 

terminate Fortran program - EXIT 17-21 

terminate job - END , 17-17 

Terminates a job step - END 17-17 

terminfo database - CURSES , 19-2 
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test for a task - TSKTEST . 14-29 

test for access - IFDNT 3-7 

test multitasking event - EVTEST 14-18 

test multitasking lock - LOCKTEST 14-25 

test sense switch - SSWITCH 17-47 

Tests a lock to determine its state (locked 

or unlocked) - LOCKTEST , 14-25 

Tests an event to determine its posted state 

-EVTEST 14-18 

Tests the sense switch - SSWITCH 17-47 

Text interface to the X Window System - XIO 19-8 

time conversion - DTTS . 15-5 

time delay - DELAY 17-14 

time elapsed wall-clock - T1MEF 15-8 

time for machine cycle - JCCYCL.... 14-20 

time in CPU - SECOND 15-7 

time in standard time - UNFITS .....15-12 

time remaining in job - TREMAIN .....15-9 

time return execution - SECOND 15-7 

time return execution - TSECND 14-27 

time to ASCII - TSDT 15-10 

time to time-stamp - DTTS , 15-5 

time-stamp conversion - DTTS . 15-5 

time-stamp to real-time - TSMT 15-11 

time-stamp units - UNITTS 15-12 

timed wait - DELAY 17-14 

TIMEF - Returns elapsed wall-clock time since 

the call to TIMER 15-8 

timing routines - TIMEF.. 15-8 

timing routines introduction - INTRO 15-1 

TMADW - Adds a word to a table... 1 1-13 

TMAMU - Reports table management operation 

statistics 11-14 

TMATS - Allocates table space 11-15 

TMLT - Performs triple-precision arithmetic 2-84 

TMMEM - Requests additional memory 11-16 

TMMSC - Searches the table with a mask to 

locate a specific field 11-17 

TMMVE - Moves memory (words) 1 1-18 

TMPTS - Presets table space . 11-19 

TMSRC - Searches the table with an optional 

mask to locate a specific field within 

an entry and an offset 1 1-20 

TMSS - Performs triple-precision arithmetic 2-84 

TM VSC - Searches a vector table for the 

search argument * .. 1 1-21 

TR - Translates a string from one code to 

another using a translation table ,8-16 

trace - SETPLIMQ 16-12 

traceback level - TRBKLVL. 16-21 

tracing - SETPLIMQ 16-12 

trailing blank to null conversion - RBN 8-15 

transfer bidirectional memory - SENSEBT 17-43 

transfer bytes or bits -MOV 10-5 

transfer data asynchronously - AQREAD 12-15 

transfer upon abort - SETRPV 17-45 

Transfers sign of numbers - SIGN 2-76 

translate ASCII to integer - CHCONV 8-10 

translate characters - TRRL... 8-17 

translate string - TR , 8-16 

Translates a string from one code to another 

using a translation table - TR * 8-16 

Translates characters stored one character 

per word - TRR1 ..... ..8-17 
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TRBK - Lists all subroutines active in the 

current calling sequence 16-20 

TRBKLVL - Returns information on current 

level of calling sequence 16-21 

TREMAIN - Returns the CPU time (in 

floating-point seconds) 15-9 

TRIMLEN - Returns the number of characters in 

a string 10-7 

triple precision - TADD . ...2-84 

triple-precision addition - TADD .2-84 

triple-precision arithmetic - TADD 2-84 

triple-precision division - TADD 2-84 

triple-precision multiplication - TADD .2-84 

triple-precision subtraction - TADD .......2-84 

TRR1 - Translates characters stored one 

character per word. 8-17 

truncation - AINT 2-12 

TSDT - Converts time-stamps to ASCII date and 

time 15-10 

TSECND - Returns elapsed CPU time for a 

calling task during a multi tasked program 14-27 

TSKSTART - Initiates a task 14-28 

TSKTEST - Returns a value indicating whether 

the indicated task exists ....14-29 

TSKTUNE - Modifies tuning parameters within 

the library scheduler 14-30 

TSKVALUE - Retrieves user identifier 

specified in task control array 14-31 

TSKWAIT - Waits for the indicated task to 

complete execution 14-32 

TSMT - Converts time-stamp to a corresponding 

real-time value, and vice versa 15-1 1 

TSSS - Performs triple-precision arithmetic 2-84 

TSUB - Performs triple-precision arithmetic 2-84 

Tune parameters controlling multitasking 

history trace - BUFTUNE .,..14-10 

tune parameters for multitasking - TSKTUNE 14-30 

Turns on and off the classes of messages to 

the user logfile - ECHO 17-16 

twos complement compare - KOMSTR 10-4 

type -CMPLX 2-27 

type conversion - CMPLX .....2-27 

type conversion - DBLE .........2-39 

type conversion - INT 2-49 

type conversion - REAL 2-68 

type conversion on input - RNLTYPE 12-57 

type converter (complex) - CMPLX 2-27 

type convener - DBLE.... .2-39 

type converter - INT 2-49 

type converter - REAL 2-68 

type mismatch on input - RNLTYPE 12-57 

U32 - Packs/unpacks 32-bit words into or from 

Cray 64-bit words 9-3 

U6064 - Packs/unpacks 60-bit words into or 

from Cray 64-bit words 9-4 

UNAME - Gets name of current operating system 18-8 

unblocked copy - COPYU 13-5 

unblocked dataset dump to - DUMPJOB 16-5 

unblocked dataset skip -SKIPU 13-13 

unbuffered dataset open - WOPENU 12-78 

unconjugated rank 1 update - CGERU 4-22 

Unformatted dump of multitasking history 

trace buffer - BUFDUMP ..14-8 

unit increments - MXM 4-86 
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unit increments - MXV 4-92 

unit NAMELIST errors - RNLECHO ...12-55 

UNI' ITS - Returns time-stamp units in 

specified standard time units 15-12 

UNPACK - Expands stored data. 9-5 

unpack 60 into 64 bits - P6460 9-4 

unpack data - UNPACK 9-5 

unpack from 32 to 64 bits - P32 9-3 

unused heap return -HPSHRINK 11-10 

Updates CRT screens - CURSES . 19-2 

uppercase letters - TR 8-16 

USCCTC - Converts IBM EBCDIC data to ASCII 

data and vice versa ...8-18 

USCCn - Converts IBM EBCDIC data to ASCII 

data and vice versa 8-18 

USDCTC - Converts IBM 64-bit floating-point 

numbers to Cray 64-bit single-precision 

numbers 8-19 

USDCn - Converts Cray 64-bit 

single-precision, floating-point numbers to IBM 

64-bit double precision numbers .8-20 

user job area dump - DUMPJOB 16-5 

USICTC - Converts IBM INTEGERS and INTEGERS 

numbers to Cray 64 -bit integer 

numbers, and vice versa 8-21 

USICTI - Converts IBM INTEGER*2 and INTEGERM 

numbers to Cray 64 -bit integer 

numbers, and vice versa .8-21 

USICTP - Converts a Cray 64-bit integer to 

IBM packed-decimal field 8-22 

USLCTC - Converts IBM LOGICAL* 1 and LOGIC AL*4 

values into Cray 64 -bit logical 

values, and vice versa 8-23 

USLCTI - Converts IBM LOGICAL* 1 and LOGICAL*4 

values into Cray 64-bit logical 

values, and vice versa .8-23 

USPCTC - Converts a specified number of bytes 

of an IBM packed-decimal field to a 

64-bit integer field 8-24 

USSCTC - Converts IBM 32-bit floating-point 

numbers to Cray 64-bit single-precision 

numbers , 8-25 

USSCn - Converts Cray 64-bit 

single-precision, floating-point numbers to IBM 

32-bit single-precision numbers 8-26 

value of JCL symbol - JSYMSET 17-32 

values in a table - INFLMAX 6-9 

values in a vector - INTMAX ...6-10 

variable bit or byte move - MOV . 10-5 

variable byte replace - BYT .10-2 

variable comparison - KOMSTR..... 10-4 

variable NAMELIST on new line - WNLLINE 12-74 

variable search - FINDCH 10-3 

VAX 32-bit floating-point to 64-bit 

single-precision - VXSCTC 8-34 

VAX 64-bit complex to Cray complex conversion 

-VXZCTC. 8-36 

VAX 64-bit D conversion - VXDCTC 8-27 

VAX 64-bit G format to single -precision 

conversion - VXGCTC 8-29 

VAX JNTEGER*2 to 64-bit integer conversion - 

VXICTC ...8-31 



VAX logical value to 64-bit logical value 

conversion - VXLCTC 8-33 

vector addition - SSUM 4-133 

vector addition - SXMPY 4-156 

vector element absolute value addition - SASUM 4-101 

vector element addition - SASUM 4-101 

vector mask write - FXP 16-6 

vector object - IILZ 6-8 

vector search - CLUSEQ ..,6-5 

vector search - CLUSFLT 6-6 

vector search - CLUSILT 6-7 

vector search - INTRO 6-1 

vector search - WHENMEQ 6-25 

vector search - WHENMLT 6-26 

vector table search - TMVSC 11-21 

video attributes - CURSES 19-2 

VM write - FXP 16-6 

volume switch - SWTTCHV 12-66 

volume switching - SVOLPRC 12-65 

VXDCTC - Converts VAX 64-bit D format numbers 

to Cray single-precision numbers 8-27 

VXDCTI - Converts Cray 64-bit 

single-precision, floating-point numbers to VAX D 

format floating-point numbers 8-28 

VXGCTC - Converts VAX 64-bit G format numbers 

to Cray single-precision numbers 8-29 

VXGCTI - Converts Cray 64-bit 

single-precision, floating-point numbers to VAX G 

format floating-point numbers 8-30 

VXICTC - Converts VAX INTEGER*2 or INTEGERM 

to Cray 64-bit integers 8-31 

VXICn - Converts Cray 64-bit integers to 

either VAX INTEGERS or INTEGERM numbers8-32 
VXLCTC - Converts VAX logical values to Cray 

64-bit logical values 8-33 

VXSCTC - Converts VAX 32-bit floating-point 

numbers to Cray 64-bit single-precision 

numbers 8-34 

VXSCTI - Converts Cray 64-bit 

single-precision, floating-point to VAX F format 

single-precision, floating-point 8-35 

VXZCTC - Converts VAX 64-bit complex numbers 

to Cray complex numbers 8-36 

VXZCn - Converts Cray complex numbers to VAX 

complex numbers 8-37 

wait -DELAY 17-14 

wait for AQIO requests - AQWAIT 12-21 

wait for event - ERECALL ....17-18 

wait for I/O - WAITMS 12-69 

wait for multitasking task - TSKWATT 14-32 

wait for task completion - TSKWATT 14-32 

WATTDR - Waits for completion of an 

asynchronous I/O operation 12-69 

WAITMS - Waits for completion of an 

asynchronous I/O operation 12-69 

Waits for completion of an asynchronous I/O 

operation - WAITMS 12-69 

Waits for the indicated task to complete 

execution - TSKWATT 14-32 

Waits on a completion of asynchronous queued 

I/O requests - AQWAIT 12-21 

wall-clock time function - TIMEF 15-8 

WCHECK - Checks word-addressable file status 12-70 
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WCLOSE - Closes a word-addressable, 

random-access dataset . 12-71 

WCLOSEU - Closes a word-addressable, 

unbuffered random-access dataset 12-72 

Weiner-Levinson linear equations - OPFXLT ,,...4-98 

WHENEQ - Finds all array elements equal to or 

not equal to the target 6-22 

WHENFGE - Finds all real array elements in 

relation to the real target ........6-23 

WHENFGT - Finds all real array elements in 

relation to the real target 6-23 

WHENFLE - Finds all real array elements in 

relation to the real target 6-23 

WHENFLT - Finds all real array elements in 

relation to the real target 6-23 

WHENIGE - Finds all integer array elements in 

relation to the integer target 6-24 

WHENIGT - Finds all integer array elements in 

relation to the integer target 6-24 

WHENILE - Finds all integer array elements in 

relation to the integer target. 6-24 

WHENILT - Finds all integer array elements in 

relation to the integer target 6-24 

WHENMEQ - Finds the index of occurrences 

equal or not equal to a scalar within a 

field in a vector. 6-25 

WHENMGE - Finds the index of occurrences in 

relation to a scalar within a field in 

a vector 6-26 

WHENMGT - Finds the index of occurrences in 

relation to a scalar within a field in 

a vector 6-26 

WHENMLE - Finds the index of occurrences in 

relation to a scalar within a field in 

a vector .6-26 

WHENMLT - Finds the index of occurrences in 

relation to a scalar within a field in 

a vector , 6-26 

WHENMNE - Finds the index of occurrences 

equal or not equal to a scalar within a 

field in a vector. , 6-25 

WHENNE - Finds all array elements equal to or 

not equal to the target 6-22 

window routines - CURSES 19-2 

windows -XLIB 19-10 

Winograd - CGEMMS 4-15 

Winograd - SGEMMS 4-110 

WNLDELM - Provides user control of output 12-73 

WNLFLAG - Provides user control of output 12-73 

WNLLINE - Allows each NAMELIST variable to 

begin on a new line 12-74 

WNLLONG - Indicates output line length 12-75 

WNLREP - Provides user control of output 12-73 

WNLSEP - Provides user control of output ....12-73 

WOPEN - Opens a word-addressable, 

random-access dataset 12-76 

WOPENU - Opens a word-addressable, 

random-access dataset, unbuffered 12-78 

word add to table - TMADW 11-13 

word addressable open - WOPEN 12-76 

word addressable open - WOPENU ..12-78 

word pack and unpack -P32 ..9-3 

word shift - SHIFTL ,.,..,......2-72 

word shift - SHIFTR 2-74 

word-addressable dataset close - WCLOSEU 12-72 



word-addressable dataset read - GETWA 12-38 

word-addressable file check - WCHECK .12-70 

word-addressable file close - WCLOSE 12-71 

word-addressable file read - GETWAU 12-40 

word-addressable write - PUTWA 12-46 

word-addressable write - PUTWAU 12-47 

words move - TMMVE 1148 

words read - READ 12-49 

WRITDR - Writes to a random access dataset on 

disk 12-83 

WRITE - Writes words, full or partial record 

mode ....12-80 

write AQIO - AQWRITE 12-22 

write characters - WRITEC 12-81 

write EOD-EODW 13-6 

write Exchange Package - FXP 16-6 

write IBM words - WRIHBM 12-82 

write master index - CLOSMS 12-28 

write to random access dataset - WRJTMS 12-83 

write to random-access - PUTWA ....12-46 

write to random-access - PUTWAU ....12-47 

write words - WRITE 12-80 

WRITEC - Writes characters, full or partial 

record mode 12-81 

WR1TECP - Writes characters, full or partial 

record mode 12-81 

WRTTEP - Writes words, full or partial record 

mode , 12-80 

Writes characters, full or partial record 

mode - WRITEC 12-81 

Writes master index and closes random access 

dataset -CLOSMS 12-28 

Writes to a random access dataset on disk - 

WRITMS 12-83 

Writes to a word-addressable, random-access 

dataset - PUTWA , , 12-46 

Writes to a word-addressable, random-access 

dataset, unbuffered - PUTWAU 12-47 

Writes two IBM 32-bit floating-point words - 

WRTTIBM... 12-82 

Writes words, full or partial record mode - 

WRITE 12-80 

WRITIBM - Writes two IBM 32-bit 

floating-point words 12-82 

writing solutions to new vector - FOLR2 4-73 

WRITMS - Writes to a random access dataset on 

disk 12-83 

X Window System interface library - XLIB 19-10 

X windows -XIO 19-8 

xio - Text interface to the X Window System 19-8 

Xlib - C Language X Window System Interface 

Library 19-10 

XOR - Computes logical difference 2-58 

XPFMT - Produces a printable image of an 

Exchange Package 16-22 

zero bits count - LEADZ 2-52 

zero fill on right shift - SHIFTR 2-74 

zero fill shift - SHIFTL 2-72 
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Your reactions to this manual will help us provide you with better documentation. Please take a moment lo 
check the spaces below, and use the blank space for additional comments. 

1) Your experience with computers: 0-1 year 1-5 years 5+ years 

2) Your experience with Cray computer systems: 0-1 year 1-5 years 5+ years 

3) Your occupation: computer programmer non-computer professional 

other (please specify): 

4) How you used this manual: in a class as a tutorial or introduction as a reference guide 

for troubleshooting 

Using a scale from 1 (poor) to 10 (excellent), please rate this manual on the following criteria: 

5) Accuracy 8) Physical qualities (binding, printing) 

6) Completeness 9) Readability 

7) Organization 1 0) Amount and quality of examples 



Please use the space below, and an additional sheet if necessary, for your other comments about this 
manual. If you have discovered any inaccuracies or omissions, please give us the page number on which 
the problem occurred. We promise a quick reply to your comments and questions. 
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Company 

Telephone _ 
Today's Date 



Address 

City 

State/ Country 
Zip Code 
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1 345 Northland Drive 
Mendota Heights, MN 55120 
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Your reactions to this manual will help us provide you with better documentation. Please take a moment to 
check the spaces below, and use the blank space for additional comments. 

1 ) Your experience with computers: 0-1 year 1-5 years 5+ years 

2) Your experience with Cray computer systems: J3-1 year 1-5 years 5+ years 

3) Your occupation: computer programmer non-computer professional 

other (please specify): 

4) How you used this manual: in a class as a tutorial or introduction as a reference guide 

for troubleshooting 

Using a scale from 1 (poor) to 10 (excellent), please rate this manual on the following criteria: 

5) Accuracy 8) Physical qualities (binding, printing) 

6) Completeness 9) Readability 

7) Organization 10) Amount and quality of examples 



Please use the space below, and an additional sheet if necessary, for your other comments about this 
manual. If you have discovered any inaccuracies or omissions, please give us the page number on which 
the problem occurred. We promise a quick reply to your comments and questions. 



Name 
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Telephone _ 
Today's Date 



Address 

City 

State/ Country 
Zip Code 
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NEW FEATURES (COS only) 



CGBMV 


Multiplies a complex vector by a complex general band matrix 


CGEMM 


Multiplies a complex general matrix by a complex general matrix 


CGEMMS 


Multiplies a complex general matrix by a complex general matrix using Strassen's algorithm 


CGEMV 


Multiplies a complex vector by a complex general matrix 


CGERC 


Performs conjugated rank 1 update of a complex general matrix 


CGERU 


Performs unconjugated rank 1 update of a complex general mairix 


CHBMV 


Multiplies a complex vector by a complex Hermitian band matrix 


CHEMM 


Multiplies a complex general matrix by a complex Hermitian matrix 


CHEMV 


Multiplies a complex vector by a complex Hermitian matrix 


CHER 


Performs Hermitian rank 1 update of a complex Hermitian matrix 


CHER2 


Performs Hermitian rank 2 update of a complex Hermitian matrix 


CHER2K 


Performs Hermitian rank 2k update of a complex Hermitian matrix 


CHERK 


Performs Hermitian rank k update of a complex Hermitian matrix 


CSYMM 


Multiplies a complex general matrix by a complex symmetric matrix 


CSYR2K 


Performs symmetric rank 2k update of a complex symmetric matrix 


CSYRK 


Performs symmetric rank k update of a complex symmetric matrix 


CTBMV 


Multiplies a complex vector by a complex triangular band matrix 


CTBSV 


Solves a complex triangular banded system of equations 


CTRMM 


Multiplies a complex general matrix by a complex triangular matrix 


CTRMV 


Multiplies a complex vector by a complex triangular matrix 


CTRSM 


Solves a complex triangular system of equations with multiple right-hand sides 
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SGEMM 


Multiplies a real general matrix by a real general matrix 


SGEMMS 


Multiplies a real general matrix by a real general matrix using Strassen's algorithm 


SSYMM 


Multiplies a real general matrix by a real symmetric matrix 


SSYR2K 


Performs symmetric rank 2k update of a real symmetric matrix 



SSYRK Performs symmetric rank k update of a real symmetric matrix 

STRMM Multiplies a real general matrix by a real triangular matrix 

STRSM Solves a real triangular system of equations with multiple right-hand sides 

OSRCHM Searches an ordered integer array and returns index of the first location 

that is equal to the integer target 

AQOPENDV Opens a dataset or file for asynchronous queued I/O, allowing the user to specify 
dataset size and physical location 

GETWAU Asynchronously reads a number of words from the disk, directly to user 

PUTWAU Writes to a word-addressable, random-access dataset, unbuffered 

WCHECK Checks word-addressable file status 

WCLOSEU Closes a word-addressable, unbuffered random-access dataset 

WOPENU Opens a word-addressable, random-access dataset, unbuffered 



